Ticket #20114 (closed PLIP: fixed)

Opened 17 months ago

Last modified 7 months ago

Ship with plone.api

Reported by: zupo Owned by: jaroel
Priority: minor Milestone: 5.0
Component: Unknown Version:
Keywords: Cc:

Description (last modified by jaroel) (diff)

Proposer: Nejc Zupan (zupo)
Seconder: None as yet

Motivation

The plone.api package has gained significant popularity. It allows integrators to write cleaner code and stay productive. It promotes one single way to do things. It enforces best practice and defines a code style.

The main goals if this PLIP is to get plone.api shipped with Plone and to allow other core packages to use it, therefore making core code more readable and setting a good example for integrators looking into the core code for example on how things work.

Assumptions

We assume that plone.api is in fact a recommended best practice and that its style guide is a community-accepted style guide.

Proposal & Implementation

This PLIP will make Products.CMFPlone depend on plone.api, effectively shipping plone.api with other core packages and allow other packages to use is.

Implementation:

  • ship plone.api as a core package
  • all core packages are allowed to use plone.api in tests
  • a core package is allowed to use plone.api only if plone.api does not depend on it (to prevent circular dependencies and tightly coupled code)
  • in order to be able to respect the above rule, plone.api needs remove its dependency on the "Plone" package and rather specify actual dependencies in its setup.py
  • besides this, plone.api needs to keep an auto-updated list of all of its dependencies and dependencies of these dependencies so core committers can quickly see if the package they are working on is allowed to use plone.api or not
  • to ensure the "plone.api usage in core" rule, we need a Jenkins job that checks that no blacklisted packages use plone.api

Deliverables

Code:

  • remove any plone.app.* dependencies from plone.api
  • remove "Plone" as a dependency from plone.api's setup.py
  • add actual dependencies to plone.api's setup.py
  • create a script that gets all dependencies (and dependencies of dependencies) and dumps them into BLACKLISTED_PACKAGES.txt file
  • update Makefile to run the above script after every buildout

CI:

  • Add a Jenkins job that ensures no blacklisted packages use plone.api by using the latest BLACKLISTED_PACKAGES.txt from plone.api master.

Documentation:

  • update plone.api introduction & narrative documentation indicating that plone.api is now the official Plone best practice
  • deprecate rants and sections in plone.api docs that consider plone core as an external thing and plone.api as only a proxy over core -> now plone.api will be part of core
  • document what is BLACKLISTED_PACKAGES.txt and why it's there

Risks

  • Circular dependencies.
  • Tightly coupled code by having a package use plone.api and plone.api using this same package. Multiply by 300 and boom.

Participants

Nejc Zupan

Progress

The preparation for this PLIP is tracked at  https://github.com/plone/plone.api/issues/180.

Change History

comment:1 Changed 17 months ago by timo

  • Type changed from Bug to PLIP

comment:2 Changed 17 months ago by khink

  • Description modified (diff)

comment:3 Changed 17 months ago by khink

Why should we remove plone.app.* dependencies from plone.api? Isn't there any of the "20% things we do 80% of the time" that are in on of these packages? plone.app.user, plone.app.discussion?

comment:4 Changed 17 months ago by cwainwright

  • Status changed from new to confirmed

Marking ticket as confirmed to get it out of the pile o' spam

comment:5 Changed 17 months ago by gforcada

@khink, the idea behind that is to move that functionality provided in plone.app.* packages directly to plone.api to avoid circular dependencies.

plone.app.discussion will most probably want to use plone.api.portal.get_tool to get the catalog and search for comments and so on, but if plone.api on its own already provides an API to, let's say, create comments (plone.api.content_create_comment?) we have a circular dependency.

So the less plone* packages plone.api depend on, all the best, as all those packages will be able to use plone.api without any problem.

comment:6 Changed 17 months ago by jaroel

  • Owner set to jaroel
  • Status changed from confirmed to assigned
  • Description modified (diff)
  • Summary changed from Ship with and use plone.api to Ship with plone.api

comment:7 Changed 17 months ago by jaroel

  • Description modified (diff)

comment:8 Changed 13 months ago by jaroel

  • Milestone changed from 4.x to 5.0

comment:10 Changed 7 months ago by jaroel

  • Status changed from assigned to closed
  • Resolution set to fixed

plone.api is added as a dependency for Products.CMFPlone. plone/Products.CMFPlone#873

Note: See TracTickets for help on using tickets.