From 3c547df8775d39423584c541b00c7b4df5bb0f63 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 18 Jun 2024 23:56:18 -0700 Subject: [PATCH 01/69] Clean up PR #1670 --- coredev/agreement.md | 17 +- coredev/continous-integration.md | 13 +- coredev/contributors_agreement_explained.md | 19 +- coredev/culture.md | 2 +- coredev/documentation.md | 39 +- coredev/getting-started-with-development.md | 92 ++-- coredev/git.md | 13 +- coredev/guidelines.md | 37 +- coredev/index.md | 9 +- coredev/mrdeveloper.md | 6 +- coredev/packages-dependencies.md | 495 +++++++++--------- coredev/plip-review.md | 60 +-- coredev/plips.md | 84 ++- coredev/release.md | 71 +-- coredev/roboto.md | 27 +- coredev/troubleshooting.md | 15 +- docs/conf.py | 6 + .../core/continuous-integration.md | 98 ++++ docs/contributing/core/documentation.md | 81 +++ docs/contributing/core/index.md | 248 +++++++++ docs/contributing/core/mrdeveloper.md | 36 ++ .../contributing/core/package-dependencies.md | 350 +++++++++++++ docs/contributing/core/plip-review.md | 101 ++++ docs/contributing/core/plips.md | 276 ++++++++++ docs/contributing/core/release.md | 127 +++++ docs/contributing/core/troubleshooting.md | 55 ++ docs/contributing/index.md | 38 +- docs/glossary.md | 11 +- requirements.txt | 1 + styles/Vocab/Plone/accept.txt | 6 + 30 files changed, 1886 insertions(+), 547 deletions(-) create mode 100644 docs/contributing/core/continuous-integration.md create mode 100644 docs/contributing/core/documentation.md create mode 100644 docs/contributing/core/index.md create mode 100644 docs/contributing/core/mrdeveloper.md create mode 100644 docs/contributing/core/package-dependencies.md create mode 100644 docs/contributing/core/plip-review.md create mode 100644 docs/contributing/core/plips.md create mode 100644 docs/contributing/core/release.md create mode 100644 docs/contributing/core/troubleshooting.md diff --git a/coredev/agreement.md b/coredev/agreement.md index 337895245f..53b5bd6f8d 100644 --- a/coredev/agreement.md +++ b/coredev/agreement.md @@ -7,6 +7,10 @@ myst: "keywords": "Contributing, Plone" --- +```{todo} +All this can go, it's redundant +``` + (contributing-to-plone-label)= # Contributing to Plone @@ -19,19 +23,19 @@ Sending in a contributors agreement does not guarantee your commit access to the We ask that before requesting core access you familiarize yourself a little with the community since they will help you get ramped up: -- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. +- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. -- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). +- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). There are plenty of opportunities to meet the community and start contributing through various coding sessions, either in person or on the web. You may even be able to get immediate core access at a conference if you are flexing your mad coding skills and the right people are attending. -- Get your feet wet by contributing to the [collective](https://collective.github.io/). +- Get your feet wet by contributing to the [collective](https://collective.github.io/). Don't worry about getting it perfect or asking for help. This way you get to know us and we improve our code together as a community. -- **Patches:** Historically we encouraged people to submit patches to the ticket collector. +- **Patches:** Historically we encouraged people to submit patches to the ticket collector. These tickets are usually ignored forever. Technically, for us to accept your patch, you must sign the contributors agreement. If you want to contribute fixes, please just sign the agreement and go through the standard GitHub pull request process described below until you feel comfortable to bypass review. @@ -39,7 +43,7 @@ We ask that before requesting core access you familiarize yourself a little with Once you have familiarized yourself with the community and you are excited to contribute to the core: -- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . +- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . This offers both copyright protection and ensures that the Plone Foundation is able to exercise some control over the codebase, ensuring it is not appropriated for someone's unethical purposes. For questions about why the agreement is required, please see [About the Plone Contributor Agreement ](https://plone.org/foundation/contributors-agreement). @@ -50,7 +54,6 @@ A common way to start contributing is to participate in a [Plone sprint](https:/ **Welcome to the Plone community!** - ## Dealing with pull requests on GitHub Before we can merge a pull request, we must ensure that the author has signed the Plone Contributor Agreement. @@ -58,6 +61,6 @@ Before we can merge a pull request, we must ensure that the author has signed th If they're listed in either the [Developers](https://github.com/orgs/plone/teams/developers/members) or [Contributors](https://github.com/orgs/plone/teams/contributors/members) team, the author has signed the Plone Contributor Agreement, so we can go ahead and merge. If they aren't listed there, they may have signed and returned the Plone Contributor Agreement, but they were not yet added to a team. -You can ask agreements@plone.org to verify. +You can ask to verify. Pull requests without a signed Plone Contributor Agreement can only be merged in trivial cases, and only by the release manager. diff --git a/coredev/continous-integration.md b/coredev/continous-integration.md index a1458cf41d..3f225f7f24 100644 --- a/coredev/continous-integration.md +++ b/coredev/continous-integration.md @@ -7,6 +7,10 @@ myst: "keywords": "Plone, continuous integration, best practices" --- +```{todo} +needs redaction and upgrade +``` + # Essential continuous integration practices The CI system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code. @@ -15,7 +19,6 @@ Build breakages are a normal and expected part of the development process. Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. Though, there are some essential rules that needs to be followed in order to achieve a stable build. - ## 1) Don't check in on a broken build Do not make things more complicated for the developer who is responsible for breaking the build. @@ -34,7 +37,6 @@ If this is the case, there is no way around breaking a single build for a certai In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. ``` - ## 2) Always run all commit tests locally before committing Following this practice ensures the build stays green, and other developers can continue to work without breaking the first rule. @@ -46,33 +48,28 @@ Furthermore, a common source of errors on check-in is to forget to add some file If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system. - ## 3) Wait for commit tests to pass before moving on Always monitor the build's progress, and fix the problem right away if it fails. You have a far better chance of fixing the build, if you just introduced a regression than later. Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours. - ## 4) Never go home on a broken build Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially stops all other developers from working on it. Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. It will prevent all the other developers to stop working on the build or fixing the errors that you introduced. - ## 5) Always be prepared to revert to the previous revision In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. - ## 6) Time-box fixing before reverting When the build breaks on check-in, try to fix it for ten minutes. If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. This way you will allow other developers to continue to work. - ## 7) Don't comment out failing tests Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. @@ -83,7 +80,6 @@ This means that we either caused a regression, made assumptions that are no long You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). - ## 8) Take responsibility for all breakages that result from your changes If you commit a change and all the tests you wrote pass, but others break, the build is still broken. @@ -97,7 +93,6 @@ If you think you hit such a test, try to fix it (better) or re-run the Jenkins j In any case the developer who made the commit is responsible to make it pass. - ## Further Reading Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community. diff --git a/coredev/contributors_agreement_explained.md b/coredev/contributors_agreement_explained.md index 88851f6c85..2915b5e61f 100644 --- a/coredev/contributors_agreement_explained.md +++ b/coredev/contributors_agreement_explained.md @@ -8,8 +8,7 @@ myst: --- ```{todo} -All this content should be audited against the plone.org site, probably removed, and replaced with a link to the authorative content on plone.org. -Duplicating content is a maintenance burden. +All this can go, it's redundant ``` # Contributor's Agreement for Plone explained @@ -18,8 +17,7 @@ Prospective contributors to the Plone code base are required to sign a contribut This document explains the purposes of this, along with questions and answers about what this means. -The Plone Contributor's Agreement can be found at https://plone.org/foundation/contributors-agreement. - +The Plone Contributor's Agreement can be found at . ## About the Plone Contributor Agreement @@ -28,10 +26,9 @@ Prior to the Foundation, the intellectual property of Plone was jointly held by The community members who formed the Foundation felt that having the Foundation hold these rights provides several benefits: -1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. -2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. -3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. - +1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. +2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. +3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. ## Questions and answers @@ -95,7 +92,7 @@ How much would a non-GPL version of Plone cost? > Despite this, though, many large and excellent contributions—such as Archetypes—have been made, and the Foundation hopes that companies will continue to do so. > In any event, a company that purchases a non-GPL license (should such ever become available) is contributing financial resources to our community, which can be used to further develop, market, and protect the GPL version of Plone. -- https://plone.org/foundation/contributors-agreement/agreement.pdf -- https://github.com/collective -- https://github.com/plone +- +- +- - [Policy for Contributor Agreements and patches](https://plone.org/foundation/materials/foundation-resolutions/patch-policy-052011) diff --git a/coredev/culture.md b/coredev/culture.md index 545b90996a..ff30aa2d8f 100644 --- a/coredev/culture.md +++ b/coredev/culture.md @@ -8,7 +8,7 @@ myst: --- ```{todo} -This content is probably redundant and should be purged. +All this can go, it's redundant ``` # Plone developer culture diff --git a/coredev/documentation.md b/coredev/documentation.md index a09ec6bf81..bbaec73bcb 100644 --- a/coredev/documentation.md +++ b/coredev/documentation.md @@ -6,6 +6,9 @@ myst: "property=og:title": "Writing documentation of Plone" "keywords": "documentation, Plone" --- +```{todo} +shorten & update +``` # Writing documentation @@ -13,14 +16,12 @@ For general guidance for contributing documentation, see {doc}`contributing/inde For documentation authors, see {doc}`contributing/authors`. - ## Documentation of Plone -The comprehensive resource for Plone documentation is https://6.docs.plone.org/. +The comprehensive resource for Plone documentation is . The documentation repository is on [GitHub](https://github.com/plone/documentation). Information for how to contribute to documentation can be found at {doc}`contributing/index`. - ## Documenting a package At the very least, your package should include the following forms of documentation. @@ -33,12 +34,11 @@ It should be formatted using [GitHub flavored Markdown](https://github.github.co `README.md` should include: -- A brief description of the package's purpose. -- Installation information (How do I get it working?) -- Compatibility information (what versions of Plone does it work with?) -- Links to other sources of documentation. -- Links to issue trackers, mailing lists, and other ways to get help. - +- A brief description of the package's purpose. +- Installation information (How do I get it working?) +- Compatibility information (what versions of Plone does it work with?) +- Links to other sources of documentation. +- Links to issue trackers, mailing lists, and other ways to get help. ### The manual (narrative documentation) @@ -46,27 +46,26 @@ The manual goes into further depth for people who want to know all about how to It includes topics like: -- What are its features -- How to use them (in English—not doctests!) -- Information about architecture -- Common gotchas +- What are its features +- How to use them (in English—not doctests!) +- Information about architecture +- Common gotchas The manual should consider various audiences who may need different types of information: -- End users who use Plone for content editing, but don't manage the site. -- Site administrators who install and configure the package. -- Integrators who need to extend the functionality of the package in code. -- System administrators who need to maintain the server running the software. +- End users who use Plone for content editing, but don't manage the site. +- Site administrators who install and configure the package. +- Integrators who need to extend the functionality of the package in code. +- System administrators who need to maintain the server running the software. Simple packages with limited functionality can get by with a single page of narrative documentation. In this case, it's simplest to include it in an extended `README.md`. -Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching. +Some excellent examples of a single-page README are and . If your project is moderately complex, you may want to set up your documentation with multiple pages. The preferred way to do this is to add Sphinx to your project, and host your docs on readthedocs.org, so that it rebuilds the documentation whenever you push to GitHub. If you do this, your `README.md` must link off site to the documentation. - ### Reference or API documentation An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code). @@ -74,7 +73,6 @@ It is meant for random access to remind the reader of how a particular class or If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx. - ### Changes or history ```{todo} @@ -102,7 +100,6 @@ See for a fu If a change was related to a bug in the issue tracker, the changelog entry should include a link to that issue. - ### Licenses Information about the open source license used for the package should be placed within the `docs` directory. diff --git a/coredev/getting-started-with-development.md b/coredev/getting-started-with-development.md index 5975adc21d..109b4a594e 100644 --- a/coredev/getting-started-with-development.md +++ b/coredev/getting-started-with-development.md @@ -7,27 +7,28 @@ myst: "keywords": "Plone, development" --- +```{todo} +Needs updating to Plone6, but contains useful info +``` + # Getting started with development This document assumes you want to run the current latest Plone source, fix a bug in Plone, or test an add-on in the context of the latest code, and will detail the full process. For how to write Plone Improvement Proposals (PLIPs), read {doc}`plips`. - ## Version support policy If you are triaging or fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule#91815aec-0513-40e0-a804-55ea787a8c68). - ## Dependencies -- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). -- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). -- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). +- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). +- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). +- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). You can do this through the App Store or registering through the Apple Developer Program. -- [Pillow](https://pypi.org/project/Pillow/). -- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. - +- [Pillow](https://pypi.org/project/Pillow/). +- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. +- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. (setup-development-environment)= @@ -66,9 +67,8 @@ or as a WSGI service with: To login, the defaults are: -- username: admin -- password: admin - +- username: admin +- password: admin ## Switching branches @@ -98,7 +98,6 @@ The line with a `*` by it will indicate the branch on which you are currently wo Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. ``` - ## Jenkins and mr.roboto Plone has a continuous integration (CI) setup and follows CI rules. @@ -113,33 +112,32 @@ Build breakages are a normal and expected part of the development process. Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. Though, there are some essential practices that need to be followed in order to achieve a stable build: -1. Don't check in on a broken build. Check Jenkins first. -2. Always run all commit tests locally before committing. -3. Wait for commit tests to pass before moving on. -4. Never go home on a broken build. -5. Always be prepared to revert to the previous revision. -6. Time-box fixing before reverting. -7. Don't comment out failing tests. -8. Take responsibility for all breakages that result from your changes. +1. Don't check in on a broken build. Check Jenkins first. +2. Always run all commit tests locally before committing. +3. Wait for commit tests to pass before moving on. +4. Never go home on a broken build. +5. Always be prepared to revert to the previous revision. +6. Time-box fixing before reverting. +7. Don't comment out failing tests. +8. Take responsibility for all breakages that result from your changes. See {doc}`continous-integration` for more information. Since it can be burdensome to check this manually, install the tools locally to always see the current state of the Plone CI Server: -- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). -- For macOS there is [CCMenu](http://ccmenu.org/). -- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). -- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). +- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). +- For macOS there is [CCMenu](http://ccmenu.org/). +- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). +- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). These tools were built to parse a specific file that CruiseControl, another CI tool, generated. Jenkins generates this file too. You can configure your notifier of choice with this url: `https://jenkins.plone.org/cc.xml` [which is a 404, LOL!] - ## Check out packages to fix Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. -It can be a little daunting at first to find out which packages cause the bug in question, but just ask in https://community.plone.org/ if you need some help. +It can be a little daunting at first to find out which packages cause the bug in question, but just ask in if you need some help. Once you know which packages you want, pull their source. You can get the source of the package with `mr.developer` and the checkout command, or you can go directly to editing {file}`checkouts.cfg`. @@ -177,7 +175,6 @@ In both methods, `mr.developer` will download the source from GitHub (or otherwi You can repeat this process with as many or as few packages as you need. For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. - ## Testing Locally To run a test for the specific module you modify: @@ -203,7 +200,6 @@ you may just let jenkins do this part for you. More on that below. ``` - ## Updating `CHANGES.rst` and `checkouts.cfg` Once all the tests are running locally on your machine, you are **ALMOST** ready to commit the changes. @@ -228,32 +224,30 @@ Not that you would ever skip running all tests. If your bug is in more than one release, for example 5.2 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg`. - ## Commits and pull requests Review the following checklist: -- Did you fix the original bug? -- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? -- Did you remove any extra code and lingering pdbs? -- Did you write a test case for that bug? -- DO all test cases for the modules and Plone pass? -- Did you update {file}`CHANGES.rst` in each packages you touched? -- Did you add your changed packages to {file}`checkouts.cfg`? +- Did you fix the original bug? +- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? +- Did you remove any extra code and lingering pdbs? +- Did you write a test case for that bug? +- DO all test cases for the modules and Plone pass? +- Did you update {file}`CHANGES.rst` in each packages you touched? +- Did you add your changed packages to {file}`checkouts.cfg`? If you answered *YES* to all of these questions, then you are ready to push your changes! A couple quick reminders: -- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. +- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. Otherwise, please create a `pull request` (more on that below). -- Please try to make one change per commit. +- Please try to make one change per commit. If you are fixing three bugs, make three commits. That way, it is easier to see what was done when, and easier to roll back any changes if necessary. If you want to make large changes cleaning up whitespace or renaming variables, it is especially important to do so in a separate commit for this reason. -- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! +- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! If you commit something REALLY sketchy, they will politely contact you, most likely after immediately reverting changes. - There are no official people assigned to this so if you are especially nervous, ask in https://community.plone.org/. - + There are no official people assigned to this so if you are especially nervous, ask in . ## Commit to `Products.CMFPlone` @@ -315,7 +309,7 @@ git checkout 4.2 git merge my-awesome-feature-4.2 ``` -### Branches and forks and direct commits - oh my! +### Branches and forks and direct commits - oh my ```{note} This section needs a rewrite. @@ -330,10 +324,10 @@ For Plone, this would be the version branch, whereas for most other packages thi HOWEVER, there are a few situations where a branch is appropriate. If you: -- are just getting started -- are not sure about your changes -- want feedback or code review -- are implementing a non-trivial change +- are just getting started +- are not sure about your changes +- want feedback or code review +- are implementing a non-trivial change then you should create a branch of whatever packages you are using, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. Everything about this process would be the same except you need to work on a branch. @@ -365,13 +359,12 @@ This will turn your request into a pull request on the main branch. There are people who look once a week or more for pending pull requests and will confirm whether or not it's a good fix, and give you feedback where necessary. The reviewers are informal and very nice, so don't worry. They are there to help! -If you want immediate feedback, visit https://community.plone.org/ with the pull request link and ask for a review. +If you want immediate feedback, visit with the pull request link and ask for a review. ```{note} You still need to update the file {file}`checkouts.cfg` in the correct branches of `buildout.coredev`! ``` - ## Finalize issues If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. @@ -379,7 +372,6 @@ We don't have integration with GitHub yet so it's a nice way to track changes. It also lets the reporter know that you care. If the bug is really bad, consider pinging the release manager and asking them to make a release. - ## FAQ How do I know when my package got made? diff --git a/coredev/git.md b/coredev/git.md index 9c9034f756..992de6aa6d 100644 --- a/coredev/git.md +++ b/coredev/git.md @@ -8,9 +8,7 @@ myst: --- ```{todo} -I seriously question the value of this entire guide. -I think it should be purged. -Plone should not be in the business of teaching how to use git or GitHub. +All this can go, it's redundant ``` # Working with Git and GitHub @@ -19,19 +17,17 @@ Plone should not be in the business of teaching how to use git or GitHub. Our repository on GitHub has the following layout: -- **feature branches**: +- **feature branches**: All development for new features must be done in dedicated branches, normally one branch per feature. -- **main** or **master** **branch**: +- **main** or **master** **branch**: when features get completed they are merged into the master branch; bugfixes are commited directly on the master branch, -- **tags**: +- **tags**: whenever we create a new release, we tag the repository so we can later retrace our steps, or rerelease versions. - ## Git basics Some introductory definitions and concepts, if you are already familiar enough with Git, head to next section: {ref}`general-guidelines-label`. - ### Mental working model With Git (as well as all modern [DVCS](http://en.wikipedia.org/wiki/Distributed_revision_control)), distributing changes to others is a two steps process (contrary to traditional VCS like `svn`). @@ -48,7 +44,6 @@ You can freely fix/change/remove/rework/update/... your commits afterwards. Push your changes whenever you are sure they are what you, and others, expect them to be. - ### Concepts In Git there are: diff --git a/coredev/guidelines.md b/coredev/guidelines.md index 6c9ea0236d..a931c3eb12 100644 --- a/coredev/guidelines.md +++ b/coredev/guidelines.md @@ -7,9 +7,9 @@ myst: "keywords": "" --- -```todo -This should probably be purged. -It is redundant to the default [CONTRUBITING.md](https://github.com/plone/.github/blob/main/CONTRIBUTING.md) and other files. +```{todo} +All this can go, it's redundant. +IMPORTANT: it does need a rewrite on 6.docs.plone.org as there are many packages in the wild that link to it. ``` % Note: this page is linked to from CONTRIBUTING.rst in all packages. Keep it short! @@ -23,35 +23,34 @@ Let's bring you up to speed with the minimum you need to know to start contribut ## Create an issue -- If you know the issue is for a specific package, you can add an issue there. +- If you know the issue is for a specific package, you can add an issue there. When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues). -- Please specify a few things: +- Please specify a few things: - - What steps reproduce the problem? - - What do you expect when you do that? - - What happens instead? - - Which Plone version are you using? + - What steps reproduce the problem? + - What do you expect when you do that? + - What happens instead? + - Which Plone version are you using? -- If it is a visual issue, can you add a screen shot? +- If it is a visual issue, can you add a screen shot? -- If there is an error in the Site Setup error log, please include it. +- If there is an error in the Site Setup error log, please include it. Especially a traceback is helpful. Click on the 'Display traceback as text' link if you see it in the error log. - ## Create a pull request -- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. +- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. This means that we can NOT accept pull requests from you unless this is done, so please don't put the code reviewers at risk and do it anyways. -- Add a changelog entry as file in the news directory. +- Add a changelog entry as file in the news directory. For helpful instructions, please see: -- For new features, an addition to README.rst is probably needed. +- For new features, an addition to README.rst is probably needed. A package may include other documentation that needs updating. -- All text that can be shown in a browser must be translatable. +- All text that can be shown in a browser must be translatable. Please mark all such strings as translatable. -- Be nice and use code quality checkers like flake8 and jshint. -- See if you can use git to squash multiple commits into one where this makes sense. +- Be nice and use code quality checkers like flake8 and jshint. +- See if you can use git to squash multiple commits into one where this makes sense. If you are not comfortable with git, never mind. -- If after reading this you become hesitant: don't worry. +- If after reading this you become hesitant: don't worry. You can always create a pull request, mark it as WIP (work in progress), and improve the above points later. diff --git a/coredev/index.md b/coredev/index.md index 80eb9b6130..38bf4fc7be 100644 --- a/coredev/index.md +++ b/coredev/index.md @@ -7,12 +7,15 @@ myst: "keywords": "Developing, Plone, Contributing" --- +```{todo} +Most of this can go +``` + # Development in Plone This part describes the process of development in Plone. It is primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). - ## Plone Contributor Agreement You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). @@ -20,7 +23,6 @@ You must sign the [Plone Contributor Agreement](https://plone.org/foundation/con We can **NOT** accept pull requests from you until you have signed and returned the Contributor Agreement, and been approved. Please don't put the code reviewers at risk by ignoring this requirement. - ## Contents ```{toctree} @@ -38,7 +40,6 @@ git package-dependencies ``` - ## Additional material These are some documents used as reference for this documentation. @@ -60,4 +61,4 @@ The style guides are ancient and need to be overhauled. Documenation's style is guided by Vale and the Microsoft Style Guide. See [Contributing to Documentation](https://6.docs.plone.org/contributing/index.html). -Our coding style guides are located at the [Plone Style Guide](https://5.docs.plone.org/develop/styleguide/index.html section. +Our coding style guides are located at the [Plone Style Guide]( section. diff --git a/coredev/mrdeveloper.md b/coredev/mrdeveloper.md index 83d90a553f..f1a280f210 100644 --- a/coredev/mrdeveloper.md +++ b/coredev/mrdeveloper.md @@ -7,10 +7,14 @@ myst: "keywords": "mr.developer" --- +```{todo} +Review, but keep +``` + # `mr.developer` This buildout uses `mr.developer` to manage package development. -See https://pypi.org/project/mr.developer/ for more information, or run `bin/develop help` for a list of available commands. +See for more information, or run `bin/develop help` for a list of available commands. The most common workflow to get all the latest updates is: diff --git a/coredev/packages-dependencies.md b/coredev/packages-dependencies.md index 5f673b7ce3..2f8ba1145f 100644 --- a/coredev/packages-dependencies.md +++ b/coredev/packages-dependencies.md @@ -7,26 +7,28 @@ myst: "keywords": "Architecture, packages, dependecies, Plone" --- +```{todo} +Needs grammar/style check, and re-do the ASCII art as Mermaid diagram for added clarity and visuals +``` + # Architecture: packages and dependecies This chapter describes the architecture of Plone's packages and dependencies. - ## Motivation In the past, lots of indirections were introduced in Plone's packages and dependecies. Our goal in the long run is to untangle them and get a direct dependency graph. This document shows the current state as an orientation. - ## Overview There are multiple level of dependencies: -- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) -- Python level (imports) -- ZCML level (includes) -- testing (need for layers, such as functional testing) +- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) +- Python level (imports) +- ZCML level (includes) +- testing (need for layers, such as functional testing) We do not have any circular dependencies at the package level anymore. This was solved already. @@ -34,7 +36,6 @@ This was solved already. Nevertheless we have indirection on all other levels. Since Plone consists of a lot of packages, it is complex to untangle those. - ## Mental model A base mental model for how Plone is organized in Plone 6 since alpha 4 is shown in the following diagram: @@ -96,9 +97,8 @@ A base mental model for how Plone is organized in Plone 6 since alpha 4 is shown As a rough model we have two packages as dividing lines: -1. `Products.CMFPlone` -2. `plone.base` - +1. `Products.CMFPlone` +2. `plone.base` ## Packages in detail @@ -106,263 +106,256 @@ If we look deeper into those, we have more sub-dividers, but first group all int Then, based on the 6.0.0.a4 release, these are the packages: - ### Above `Products.CMFPlone` -- Plone -- plone.api -- plone.app.iterate -- plone.app.upgrade -- plone.restapi -- plone.volto -- Products.CMFPlacefulWorkflow - +- Plone +- plone.api +- plone.app.iterate +- plone.app.upgrade +- plone.restapi +- plone.volto +- Products.CMFPlacefulWorkflow ### Between `Products.CMFPlone` and `plone.base` -- collective.monkeypatcher -- plone.app.caching -- plone.app.content -- plone.app.contentlisting -- plone.app.contentmenu -- plone.app.contentrules -- plone.app.contenttypes -- plone.app.customerize -- plone.app.dexterity -- plone.app.discussion -- plone.app.event -- plone.app.i18n -- plone.app.intid -- plone.app.layout -- plone.app.linkintegrity -- plone.app.locales -- plone.app.lockingbehavior -- plone.app.multilingual -- plone.app.portlets -- plone.app.querystring -- plone.app.redirector -- plone.app.registry -- plone.app.relationfield -- plone.app.textfield -- plone.app.theming -- plone.app.users -- plone.app.uuid -- plone.app.versioningbehavior -- plone.app.viewletmanager -- plone.app.vocabularies -- plone.app.widgets -- plone.app.workflow -- plone.app.z3cform -- plone.browserlayer -- plone.cachepurging -- plone.contentrules -- plone.formwidget.namedfile -- plone.formwidget.recurrence -- plone.i18n -- plone.namedfile -- plone.outputfilters -- plone.portlet.collection -- plone.portlet.static -- plone.portlets -- plone.protect -- plone.resourceeditor -- plone.rfc822 -- plone.schemaeditor -- plone.session -- plone.staticresources -- plone.stringinterp -- plone.theme -- plonetheme.barceloneta -- Products.isurlinportal - +- collective.monkeypatcher +- plone.app.caching +- plone.app.content +- plone.app.contentlisting +- plone.app.contentmenu +- plone.app.contentrules +- plone.app.contenttypes +- plone.app.customerize +- plone.app.dexterity +- plone.app.discussion +- plone.app.event +- plone.app.i18n +- plone.app.intid +- plone.app.layout +- plone.app.linkintegrity +- plone.app.locales +- plone.app.lockingbehavior +- plone.app.multilingual +- plone.app.portlets +- plone.app.querystring +- plone.app.redirector +- plone.app.registry +- plone.app.relationfield +- plone.app.textfield +- plone.app.theming +- plone.app.users +- plone.app.uuid +- plone.app.versioningbehavior +- plone.app.viewletmanager +- plone.app.vocabularies +- plone.app.widgets +- plone.app.workflow +- plone.app.z3cform +- plone.browserlayer +- plone.cachepurging +- plone.contentrules +- plone.formwidget.namedfile +- plone.formwidget.recurrence +- plone.i18n +- plone.namedfile +- plone.outputfilters +- plone.portlet.collection +- plone.portlet.static +- plone.portlets +- plone.protect +- plone.resourceeditor +- plone.rfc822 +- plone.schemaeditor +- plone.session +- plone.staticresources +- plone.stringinterp +- plone.theme +- plonetheme.barceloneta +- Products.isurlinportal ### The foundation below `plone.base` - #### Plone world -- borg.localrole -- plone.alterego -- plone.autoform -- plone.autoinclude -- plone.batching -- plone.behavior -- plone.caching -- plone.dexterity -- plone.event -- plone.folder -- plone.indexer -- plone.intelligenttext -- plone.keyring -- plone.locking -- plone.memoize -- plone.registry -- plone.resource -- plone.rest -- plone.scale -- plone.schema -- plone.subrequest -- plone.supermodel -- plone.transformchain -- plone.uuid -- plone.z3cform -- Products.DateRecurringIndex -- Products.ExtendedPathIndex -- Products.MimetypesRegistry -- Products.PlonePAS -- Products.PortalTransforms -- Products.statusmessages - +- borg.localrole +- plone.alterego +- plone.autoform +- plone.autoinclude +- plone.batching +- plone.behavior +- plone.caching +- plone.dexterity +- plone.event +- plone.folder +- plone.indexer +- plone.intelligenttext +- plone.keyring +- plone.locking +- plone.memoize +- plone.registry +- plone.resource +- plone.rest +- plone.scale +- plone.schema +- plone.subrequest +- plone.supermodel +- plone.transformchain +- plone.uuid +- plone.z3cform +- Products.DateRecurringIndex +- Products.ExtendedPathIndex +- Products.MimetypesRegistry +- Products.PlonePAS +- Products.PortalTransforms +- Products.statusmessages #### Zope ecosystem -- Chameleon -- diazo -- five.customerize -- five.intid -- five.localsitemanager -- icalendar -- Products.CMFCore -- Products.CMFDiffTool -- Products.CMFDynamicViewFTI -- Products.CMFEditions -- Products.CMFUid -- Products.DCWorkflow -- Products.ExternalMethod -- Products.GenericSetup -- Products.MailHost -- Products.PluggableAuthService -- Products.PluginRegistry -- Products.PythonScripts -- Products.Sessions -- Products.SiteErrorLog -- Products.StandardCacheManagers -- Products.ZopeVersionControl -- repoze.xmliter -- webresource -- z3c.caching -- z3c.form -- z3c.formwidget.query -- z3c.objpath -- z3c.pt -- z3c.relationfield -- z3c.zcmlhook -- zc.recipe.egg -- zc.relation -- zodbverify -- zope.copy -- zope.intid -- zope.keyreference - +- Chameleon +- diazo +- five.customerize +- five.intid +- five.localsitemanager +- icalendar +- Products.CMFCore +- Products.CMFDiffTool +- Products.CMFDynamicViewFTI +- Products.CMFEditions +- Products.CMFUid +- Products.DCWorkflow +- Products.ExternalMethod +- Products.GenericSetup +- Products.MailHost +- Products.PluggableAuthService +- Products.PluginRegistry +- Products.PythonScripts +- Products.Sessions +- Products.SiteErrorLog +- Products.StandardCacheManagers +- Products.ZopeVersionControl +- repoze.xmliter +- webresource +- z3c.caching +- z3c.form +- z3c.formwidget.query +- z3c.objpath +- z3c.pt +- z3c.relationfield +- z3c.zcmlhook +- zc.recipe.egg +- zc.relation +- zodbverify +- zope.copy +- zope.intid +- zope.keyreference #### Zope core -- AccessControl -- Acquisition -- AuthEncoding -- beautifulsoup4 -- BTrees -- DateTime -- DocumentTemplate -- ExtensionClass -- Missing -- MultiMapping -- Persistence -- persistent -- Products.BTreeFolder2 -- Products.ZCatalog -- Record -- RestrictedPython -- transaction -- zc.lockfile -- ZConfig -- zdaemon -- ZEO -- zExceptions -- ZODB -- ZODB3 -- zodbpickle -- Zope -- zope.annotation -- zope.app.locales -- zope.browser -- zope.browsermenu -- zope.browserpage -- zope.browserresource -- zope.cachedescriptors -- zope.component -- zope.componentvocabulary -- zope.configuration -- zope.container -- zope.contentprovider -- zope.contenttype -- zope.datetime -- zope.deferredimport -- zope.deprecation -- zope.dottedname -- zope.event -- zope.exceptions -- zope.filerepresentation -- zope.globalrequest -- zope.hookable -- zope.i18n -- zope.i18nmessageid -- zope.interface -- zope.lifecycleevent -- zope.location -- zope.pagetemplate -- zope.processlifetime -- zope.proxy -- zope.ptresource -- zope.publisher -- zope.ramcache -- zope.schema -- zope.security -- zope.sendmail -- zope.sequencesort -- zope.site -- zope.size -- zope.structuredtext -- zope.tal -- zope.tales -- zope.testbrowser -- zope.testing -- zope.traversing -- zope.viewlet -- Zope2 - +- AccessControl +- Acquisition +- AuthEncoding +- beautifulsoup4 +- BTrees +- DateTime +- DocumentTemplate +- ExtensionClass +- Missing +- MultiMapping +- Persistence +- persistent +- Products.BTreeFolder2 +- Products.ZCatalog +- Record +- RestrictedPython +- transaction +- zc.lockfile +- ZConfig +- zdaemon +- ZEO +- zExceptions +- ZODB +- ZODB3 +- zodbpickle +- Zope +- zope.annotation +- zope.app.locales +- zope.browser +- zope.browsermenu +- zope.browserpage +- zope.browserresource +- zope.cachedescriptors +- zope.component +- zope.componentvocabulary +- zope.configuration +- zope.container +- zope.contentprovider +- zope.contenttype +- zope.datetime +- zope.deferredimport +- zope.deprecation +- zope.dottedname +- zope.event +- zope.exceptions +- zope.filerepresentation +- zope.globalrequest +- zope.hookable +- zope.i18n +- zope.i18nmessageid +- zope.interface +- zope.lifecycleevent +- zope.location +- zope.pagetemplate +- zope.processlifetime +- zope.proxy +- zope.ptresource +- zope.publisher +- zope.ramcache +- zope.schema +- zope.security +- zope.sendmail +- zope.sequencesort +- zope.site +- zope.size +- zope.structuredtext +- zope.tal +- zope.tales +- zope.testbrowser +- zope.testing +- zope.traversing +- zope.viewlet +- Zope2 #### Libraries -- attrs -- cffi -- cssselect -- decorator -- docutils -- feedparser -- future -- importlib_metadata -- jsonschema -- Markdown -- multipart -- Paste -- PasteDeploy -- piexif -- Pillow -- pycparser -- PyJWT -- pyrsistent -- python_dotenv -- python_gettext -- requests -- roman -- sgmllib3k -- simplejson -- soupsieve -- Unidecode -- urllib3 -- waitress -- WebOb -- WebTest -- WSGIProxy2 -- zipp +- attrs +- cffi +- cssselect +- decorator +- docutils +- feedparser +- future +- importlib_metadata +- jsonschema +- Markdown +- multipart +- Paste +- PasteDeploy +- piexif +- Pillow +- pycparser +- PyJWT +- pyrsistent +- python_dotenv +- python_gettext +- requests +- roman +- sgmllib3k +- simplejson +- soupsieve +- Unidecode +- urllib3 +- waitress +- WebOb +- WebTest +- WSGIProxy2 +- zipp diff --git a/coredev/plip-review.md b/coredev/plip-review.md index 78aed655ad..074a182faa 100644 --- a/coredev/plip-review.md +++ b/coredev/plip-review.md @@ -7,11 +7,14 @@ myst: "keywords": "PLIP, review, Plone Improvement Proposal, Plone" --- +```{todo} +Combine with PLIP page, remove obsolete technologies, go over language +``` + # PLIP review A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. - ## Expectations A good PLIP review takes about four hours. @@ -19,7 +22,6 @@ Please plan accordingly. When you are done, if you have access to core, commit the review to the `plips` folder, and reference the PLIP in your commit message. If you do not have access, attach your review to the PLIP ticket itself. - ## Setting up the environment Follow the instructions in {doc}`getting-started-with-development`. @@ -30,48 +32,43 @@ Instead of running the buildout with the default buildout file, you will run the ./bin/buildout -c plips/plipXXXX.cfg ``` - ## Functionality review This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. - ### General -- Does the PLIP actually do what the implementers proposed? +- Does the PLIP actually do what the implementers proposed? Are there incomplete variations? -- Were there any errors running buildout? +- Were there any errors running buildout? Did the migration(s) work? -- Do error and status messages make sense? +- Do error and status messages make sense? Are they properly internationalized? -- Are there any performance considerations? +- Are there any performance considerations? Has the implementer addressed them, if so? - ### Bugs -- Are there any bugs? +- Are there any bugs? Nothing is too big nor small. -- Do fields handle wacky data? +- Do fields handle wacky data? How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? +- Is validation up to snuff and sensical? Is it too restrictive or not restrictive enough? - ### Usability Issues -- Is the implementation usable? -- How will novice end users respond to the change? -- Does this PLIP need a usability review? +- Is the implementation usable? +- How will novice end users respond to the change? +- Does this PLIP need a usability review? If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. -- Is the PLIP consistent with the rest of Plone? +- Is the PLIP consistent with the rest of Plone? For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? +- Does everything flow nicely for novice and advanced users? Is there any workflow that feels odd? -- Are there any new permissions and do they work properly? +- Are there any new permissions and do they work properly? Does their role assignment make sense? - ### Documentation Issues - Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? @@ -83,23 +80,20 @@ This way the implementer can find help if they need it. Also set a priority for the ticket. The PLIP will not be merged until all blockers and critical bugs are fixed. - ### Code Review - #### Python -- Is this code maintainable? -- Is the code properly documented? -- Does the code adhere to PEP8 standards (more or less)? -- Are they importing deprecated modules? - +- Is this code maintainable? +- Is the code properly documented? +- Does the code adhere to PEP8 standards (more or less)? +- Are they importing deprecated modules? #### JavaScript -- Does the JavaScript meet our set of JavaScript standards? +- Does the JavaScript meet our set of JavaScript standards? See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). -- Does the JavaScript work in all currently supported browsers? +- Does the JavaScript work in all currently supported browsers? Is it performant? ```{todo} @@ -109,7 +103,7 @@ See https://github.com/plone/documentation/issues/1330 #### ME/TAL -- Does the PLIP use views appropriately, avoiding too much logic? -- Is there any code in a loop that could potentially be a performance issue? -- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? +- Does the PLIP use views appropriately, avoiding too much logic? +- Is there any code in a loop that could potentially be a performance issue? +- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? +- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? diff --git a/coredev/plips.md b/coredev/plips.md index 408793d471..5de254d162 100644 --- a/coredev/plips.md +++ b/coredev/plips.md @@ -7,6 +7,10 @@ myst: "keywords": "Plone Improvement Proposal, PLIP)" --- +```{todo} +Needs language review +``` + # Plone Improvement Proposals (PLIPs) A PLIP is a Plone Improvement Proposal. @@ -14,12 +18,10 @@ It is a change to a Plone package that would affect everyone. PLIPs go through a different process than bug fixes because of their broad reaching effect. The Plone Framework Team reviews all PLIPs to be sure that it's in the best interest of the broader community to be implemented and that it is of high quality. - ## Frequently asked questions about PLIPs This section provides detailed answers to common questions about PLIPs. - ### PLIP or bugfix? In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. @@ -28,7 +30,6 @@ The Framework Team is eager to reduce its own workload and will reclassify it fo If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. The key point here is that each change must be documented, allowing it to be tracked and understood. - ### Who can submit PLIPs? Anyone who has signed a Plone Contributor Agreement can work on a PLIP. @@ -46,7 +47,6 @@ If you have ideas on new interactions or UI your ideas are more than welcome. We will help you pair up with implementers if needed. - ### What is a PLIP champion? When you submit your PLIP and it is approved, a Framework Team member who is especially excited about seeing the PLIP completed will be assigned to your PLIP as a champion. @@ -55,15 +55,14 @@ They are there to push you through completion, as well as answer any questions a A champion fulfill the following tasks. -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. +- Answer any questions the PLIP implementor has, technical or otherwise. +- Encourage the PLIP author by constantly giving feedback and encouragement. +- Keep the implementer aware of timelines, and push to get things done on time. +- Assist with finding additional help when needed to complete the implementation in a timely matter. Keep in mind that champions are in passive mode by default. If you need help or guidance, please reach out to them as soon as possible to activate help mode. - ### Can I get involved in other ways? If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. @@ -77,7 +76,6 @@ Then, follow the instructions for {doc}`reviewing a PLIP `. Thank you in advance! - ### When can I submit a PLIP? Today, tomorrow, any time! @@ -86,7 +84,6 @@ After the PLIP is accepted, the Framework Team will try to judge complexity and You can begin work immediately, and we encourage submitting fast and furious. - ### When is the PLIP due? **Summary: As soon as you get it done.** @@ -98,30 +95,27 @@ In general, we don't want to track a PLIP for more than a year. If your PLIP is accepted and we haven't seen activity in over a year, we will probably ask you to restart the whole process. - ### What happens if your PLIP is not accepted? If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. It is often the case that there are competing implementations, and we want to see it vetted as an add-on before "blessing" a preferred implementation. - ## Process Overview -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. +1. Submit a PLIP at any time. +2. PLIP is approved for inclusion into core for a given release. +3. Developer implements PLIP (code, tests, documentation). +4. PLIP is submitted for review by developer. +5. Framework Team reviews the PLIP and gives feedback. +6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. +7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. +8. PLIP is approved for merge. In rare circumstances, a PLIP will be rejected. This is usually the result of the developer not responding to feedback or dropping out of the process. Hang in there! -9. After all other PLIPs are merged, a release is cut. +9. After all other PLIPs are merged, a release is cut. Standby for bugs! - (how-to-submit-a-plip)= ## How to submit a PLIP @@ -151,16 +145,15 @@ Others may be able to point out risks or even offer up better or existing soluti Please note a few things: -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. +- It is very rare that the "Risks" section will be empty or none. +- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. +- The seconder field is REQUIRED. We will send the PLIP back to you if it is not filled in. Currently, this is just someone else who thinks your PLIP is a good idea, a +1. In the near future, we will start asking that the seconder is either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. - ### Evaluating PLIPs After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. @@ -173,41 +166,38 @@ Please keep your eyes and inbox open for changes. These are the criteria by which the framework team will review your work: -- What is size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? +- What is size and status of the work needed to be done? +- Is it already an add-on and well established? +- Is this idea well baked and expressed clearly? +- Does the work proposed belong in Plone now, or in the future? +- Is this PLIP more appropriate as a qualified add-on? +- Is this PLIP too risky? See the {doc}`plip-review` page for more information. - ## Implementing your PLIP You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. - ### General Rules -- Any new packages must be in a branch in the `plone` namespace in GitHub. +- Any new packages must be in a branch in the `plone` namespace in GitHub. You don't have to develop there, but it must be there when submitted. We recommend using branches off of the repositories under the Plone GitHub organization, and will detail that below. -- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. -- Any new code must: +- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. +- Any new code must: - - Be {doc}`properly documented `. - - Have clear code. - - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). + - Be {doc}`properly documented `. + - Have clear code. + - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). For convenience and better code quality use Python, JavaScript, and other code linting plugins in your editor. - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). + - [Be tested](https://5.docs.plone.org/develop/testing/index.html). ```{todo} Update links from Plone 5 to Plone 6 Documentation, once content is migrated. See https://github.com/plone/documentation/issues/1330 and other issues. ``` - ### Creating a new PLIP branch Create a buildout configuration file for your PLIP in the `plips` folder. @@ -242,7 +232,6 @@ zcml += Use the same naming convention when you branch existing packages. You should always branch packages when working on PLIPs. - ### Working on a PLIP To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: @@ -269,16 +258,15 @@ installed = .installed.cfg var = ./var ``` - ### Finishing up Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. This file should be called {file}`plip__notes.txt`. This should include, but is not limited to: -- URLs pointing to all documentation created and updated -- Any concerns and issues still remaining -- Any weird buildout things +- URLs pointing to all documentation created and updated +- Any concerns and issues still remaining +- Any weird buildout things Once you have finished, update your PLIP issue to indicate that it is ready for review. The Framework Team will assign 2-3 people to review your PLIP. diff --git a/coredev/release.md b/coredev/release.md index 0d6ad6c57a..674bd5b2a1 100644 --- a/coredev/release.md +++ b/coredev/release.md @@ -7,11 +7,14 @@ myst: "keywords": "Plone, release, process" --- +```{todo} +Can stay, as it needs a place to live. Check in with Release Managers to update content, if needed +``` + # Plone release process This chapter describes the process to release Plone and its packages. - ## Release process for Plone packages To keep the Plone software stack maintainable, the Python egg release process must be automated to a high degree. @@ -26,21 +29,20 @@ This command includes the following requirements. All files mentioned in this list may be written in Markdown or reStructuredText and have the appropriate file name suffix. ``` -- All releases must be hosted on PyPI. -- All versions must be tagged in version control. -- Each package must have a {file}`README` file with links to the version control repository and issue tracker. -- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. -- {file}`CHANGES` must contain release dates. -- {file}`README` and {file}`CHANGES` must be visible on PyPI. -- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. +- All releases must be hosted on PyPI. +- All versions must be tagged in version control. +- Each package must have a {file}`README` file with links to the version control repository and issue tracker. +- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. +- {file}`CHANGES` must contain release dates. +- {file}`README` and {file}`CHANGES` must be visible on PyPI. +- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. -- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). +- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). ```{seealso} [High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). ``` - ## Special packages The Plone Release Team releases the core Plone packages. @@ -56,14 +58,13 @@ These are: `plone.app.locales` : Please leave this to the i18n team lead, Vincent Fretin. - ## Plone core release process checklist -1. Check Jenkins status. +1. Check Jenkins status. Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org/). It should be green, but if it is not, fix the problem first. -2. Check out `buildout.coredev`. +2. Check out `buildout.coredev`. ```shell git clone git@github.com:plone/buildout.coredev.git @@ -73,45 +74,45 @@ These are: bin/buildout -c buildout.cfg ``` -3. Check packages for updates. +3. Check packages for updates. Check all packages for updates, add to or remove from `checkouts.cfg` accordingly. This script may help: ```shell bin/manage report --interactive ``` - + This step should not be needed, because we do the check for every single commit, but people may still have forgotten to add a package to the `checkouts.cfg` file. -4. Check packages individually. +4. Check packages individually. Use the `bin/fullrelease` script from the core development buildout. This includes extra checks that we have added in `plone.releaser`. It guides you through all the next steps. - 1. Check changelog. + 1. Check changelog. Check if `CHANGES` is up-to-date. All changes since the last release should be included. A "Fixes" or "New" header should be included, with the relevant changes under it. Upgrade notes are best placed here as well. Compare `git log HEAD...` with `CHANGES`, or from `zest.releaser` use the command `lasttaglog `. - 2. Run [pyroma](https://pypi.org/project/pyroma/). - 3. Run [check-manifest](https://pypi.org/project/check-manifest/). - 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). - 5. Check if the version in `setup.py` is correct and follows our versioning best practice. - 6. Make a release (zest.releaser: `bin/fullrelease`) - 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. - -5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. -6. Update CMFPlone version in `profiles/default/metadata.xml`. -7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. -8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). - - 1. Copy all core packages there. - 2. Possibly make an alpha or beta release of CMFPlone. - 3. Copy the `versions.cfg` file from coredev to there. - -9. Write an email to the Plone developers list announcing a pending release. + 2. Run [pyroma](https://pypi.org/project/pyroma/). + 3. Run [check-manifest](https://pypi.org/project/check-manifest/). + 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). + 5. Check if the version in `setup.py` is correct and follows our versioning best practice. + 6. Make a release (zest.releaser: `bin/fullrelease`) + 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. + +5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. +6. Update CMFPlone version in `profiles/default/metadata.xml`. +7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. +8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). + + 1. Copy all core packages there. + 2. Possibly make an alpha or beta release of CMFPlone. + 3. Copy the `versions.cfg` file from coredev to there. + +9. Write an email to the Plone developers list announcing a pending release. 10. Update `plone.app.locales` version. 11. Create a unified changelog. @@ -123,7 +124,7 @@ These are: 13. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). 14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). 15. Create a release page on [plone.org](https://plone.org/download/releases) -16. Send links to the installers list at plone-installers@lists.sourceforge.net. +16. Send links to the installers list at . 17. Wait for installers to be uploaded to Launchpad, with a link to the plone.org release page. 18. Publish release page on plone.org. 19. Update plone.org homepage links to point to the new release. diff --git a/coredev/roboto.md b/coredev/roboto.md index 89d42038f0..a195e0adec 100644 --- a/coredev/roboto.md +++ b/coredev/roboto.md @@ -7,6 +7,10 @@ myst: "keywords": "Mr. Roboto, mr.roboto, Plone" --- +```{todo} +Needs content review, it looks highly outdated with references to CVS, kgs and other obsolete tech +``` + # Mr. Roboto ```{todo} @@ -17,31 +21,30 @@ Add brief description of what is Mr. Roboto and what it does. When a push happens on GitHub, `mr.roboto` is triggered and it starts to analyze the push. -- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. +- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. In this case, we send to `plone-cvs` the commit to keep track of the commits on that list. -- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. +- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. This kgs job is a snapshot of the last working version of the `buildout.coredev` with the newest version of the package that is involved on the push. These jobs are really fast, as we only test the package applied to the kgs Plone and Python version `coredev` buildout. -- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at http://jenkins.plone.org/roboto/plips. +- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at . ```{todo} `http://jenkins.plone.org/roboto/plips` is obsolete, and returns a 404 not found. -``` - +``` ## Job finishes When Jenkins finishes a job, it makes a callback to `mr.roboto`, which in turn does the following: -- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. +- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. It does this one time only, with all the information, so no more empty mails from the GitHub notification system. -- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. +- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. We also send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. -- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. +- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. For all kgs jobs jenkins sends an email to the author with the results when is finished. -All the notifications have an URL similar to http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10. +All the notifications have an URL similar to . ```{todo} http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 is obsolete, and returns a 404 not found. @@ -49,9 +52,9 @@ http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 i On this URL, there is the commit hash, who committed it, the diff, the files, and the result for each Jenkins job. -- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. -- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. -- The author receives the results of tests failing against kgs after ten minutes after the push. +- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. +- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. +- The author receives the results of tests failing against kgs after ten minutes after the push. ```{note} In case of integration errors with other packages that may fail because of the push, kgs will not be aware of that. diff --git a/coredev/troubleshooting.md b/coredev/troubleshooting.md index db636fd806..7dcc0f98c2 100644 --- a/coredev/troubleshooting.md +++ b/coredev/troubleshooting.md @@ -7,17 +7,19 @@ myst: "keywords": "Troubleshooting, development issues, Plone" --- +```{todo} +Needs review. In general, a 'troubleshooting' page is nice, but this looks outdated +``` + # Troubleshooting This chapter describes how to troubleshoot development issues in Plone. - ## Buildout issues Buildout can be frustrating for those unfamiliar with parsing through autistic robot language. These errors are almost always a quick fix, and a little bit of understanding goes a long way. - ### Errors running `bootstrap.py` You may not even get to running buildout, and then you will already have an error. @@ -60,7 +62,6 @@ You may get the same error above again, but now that you know how to fix it, you Hooray! - ### When `mr.developer` is unhappy `mr.developer` is never unhappy, except when it is. @@ -106,7 +107,6 @@ allow-hosts += sphinx.pocoo.org Again, this is only necessary if the package wasn't found in the end. - ### `mr.developer` path errors ```console @@ -121,21 +121,18 @@ To fix, do: ln -s plips/.mr.developer.cfg ``` - ## Other random issues ```{TODO} These need to be revalidated ``` - ### Dirty packages ```console ERROR: Can't update package 'Some package', because it's dirty. ``` - #### Fix `mr.developer` is complaining because a file has been changed or added, but not committed. @@ -143,7 +140,6 @@ ERROR: Can't update package 'Some package', because it's dirty. Use `bin/develop update --force`. Adding `*.pyc *~.nib *.egg-info .installed.cfg *.pt.py *.cpt.py *.zpt.py *.html.py *.egg` to your subversion configuration's `global-ignores` has been suggested as a more permanent solution. - ### No module named zope 2 ```console @@ -153,7 +149,6 @@ ImportError: No module named Zope2" when building using a PLIP cfg file. Appears to not actually be the case. Delete {file}`mkzopeinstance.py` from {file}`bin/`, and rerun buildout to correct this if you're finding it irksome. - ### Can't open file '/Startup/run.py' Two possible fixes. @@ -163,7 +158,6 @@ If you use Python 2.4 by mistake, use 2.6 instead. Or you may need to make sure you run `bin/buildout …` after `bin/develop …`. Try removing {file}`parts/*`, {file}`bin/*`, {file}`.installed.cfg`, then re-bootstrap and re-run buildout, develop, buildout. - ### Missing PIL {file}`pil.cfg` is included within this buildout to aid in PIL installation. @@ -171,7 +165,6 @@ Run {command}`bin/buildout -c pil.cfg` to install. This method does not work on Windows. We're unable to run it by default. - ### Modified egg issues {command}`bin/develop status` is showing that the `Products.CMFActionIcons` egg has been modified, but I haven't touched it. diff --git a/docs/conf.py b/docs/conf.py index 00877dcf41..a5a763de42 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,7 @@ "sphinx.ext.viewcode", # plone.api "sphinx.ext.autosummary", # plone.api "sphinx.ext.graphviz", + "sphinxcontrib.mermaid", "notfound.extension", ] @@ -99,6 +100,8 @@ r"https://stackoverflow.com", # volto and documentation # TODO retest with latest Sphinx. r"https://web.archive.org/", # volto r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube + r"https://www.upc.edu/en", # TODO remove after their certificate is fixed + r"http://z3c.pt", # fluke where Sphinx interprets this as a URL ] linkcheck_anchors = True linkcheck_timeout = 5 @@ -179,6 +182,8 @@ "fawrench": '', } +mermaid_version = "10.9.1" + # -- Intersphinx configuration ---------------------------------- # This extension can generate automatic links to the documentation of objects @@ -329,6 +334,7 @@ "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github", } + # An extension that allows replacements for code blocks that # are not supported in `rst_epilog` or other substitutions. # https://stackoverflow.com/a/56328457/2214933 diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md new file mode 100644 index 0000000000..ed195183b9 --- /dev/null +++ b/docs/contributing/core/continuous-integration.md @@ -0,0 +1,98 @@ +--- +myst: + html_meta: + "description": "Essential continuous integration practices" + "property=og:description": "Essential continuous integration practices" + "property=og:title": "Essential continuous integration practices" + "keywords": "Plone, continuous integration, best practices" +--- + +# Essential continuous integration practices + +The {term}`CI` system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code. + +Build breakages are a normal and expected part of the development process. +The aim is to find errors and remove them as quickly as possible, without expecting perfection and zero errors. +Though, there are some essential practices that you need follow to achieve a stable build: + +## 1) Don't check in on a broken build + +Do not make things more complicated for the developer who is responsible for breaking the build. + +If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it. +This strategy gives the developer the best option to find out what caused the breakage and fix it immediately. +Fixing the build is easier with a clear look at the problem. +Checking in further changes and triggering new builds will complicate matters and lead to more problems. + +If the build is broken over a longer period of time (more than a couple of hours) you should either: + +- notify the developer who is responsible for the breakage +- fix the problem yourself +- or revert the commit so you and others can continue to work. + +```{note} +There is one exception to this rule. +Sometimes there are changes or tests that depend on changes in other packages. +If this is the case, there is no way around breaking a single build for a certain period of time. +In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. +``` + +## 2) Always run all commit tests locally before committing + +Follow this practice so the build stays green, and other developers can continue to work without breaking the first rule. + +Remember that Plone development can happen all over the world, at all times. So other developers may have checked in changes since your last synchronization. These may interact with your work. + +Therefore it's essential that you check out ({command}`git pull`) and run the tests again before you push your changes to GitHub. + +A common source of errors on check-in is to forget to add some files to the repository. +Use {command}`git status` to check and correct for this. Also double-check to not check in files that should not be part of a package, such as editor configuration files. + +## 3) Wait for commit tests to pass before moving on + +Always monitor the build's progress, and fix the problem right away if it fails. +You have a far better chance of fixing the build, if you just introduced a regression than later. +Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for you. + +## 4) Never go home on a broken build + +Take into account the first rule of CI ("Don't check in on a broken build"): breaking the build essentially stops all other developers from working on it. +Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. +It will prevent all other developers to stop working or they will need to fix the errors that you introduced. + +## 5) Always be prepared to revert to the previous revision + +In order for other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. + +## 6) Time-box fixing before reverting + +When the build breaks on check-in, try to fix it for ten minutes. +If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. +This way you will allow other developers to continue to work. + +## 7) Don't comment out failing tests + +Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. +While this impulse is understandable, it is **not acceptable**. + +The tests were passing for a while and then start to fail. +This means that you either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason. + +You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). + +## 8) Take responsibility for all breakages that result from your changes + +If you commit a change and all the tests you wrote pass, but others break, the build is still broken. +This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. +This means that you have introduced a regression bug into the application. + +It is **your responsibility** to fix all tests that are not passing because of your changes. + +There are some tests in Plone that fail randomly, the community is always working on fixing those. +If you think you hit such a test, try to fix it (better) or re-run the Jenkins job to see if it passes again. + +In any case the developer who made the commit is responsible to make it pass. + +## Further reading + +These rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community. diff --git a/docs/contributing/core/documentation.md b/docs/contributing/core/documentation.md new file mode 100644 index 0000000000..740b868815 --- /dev/null +++ b/docs/contributing/core/documentation.md @@ -0,0 +1,81 @@ +--- +myst: + html_meta: + "description": "Writing documentation of Plone" + "property=og:description": "Writing documentation of Plone" + "property=og:title": "Writing documentation of Plone" + "keywords": "documentation, Plone" +--- + +# Writing documentation + +For general guidance for contributing documentation, see {doc}`/contributing/documentation/index`. + +For documentation authors, see {doc}`/contributing/documentation/authors`. + +## Documentation of Plone + +The comprehensive resource for Plone documentation is . +The documentation repository is on [GitHub](https://github.com/plone/documentation). +Information for how to contribute to documentation can be found at {doc}`/contributing/documentation/index`. + +## Documenting a package + +At the very least, your package should include the following forms of documentation. + +### `README.md` + +The `README.md` is the first entry point for most people to your package. +It will be included on the PyPI page for your package, and on the front page of its GitHub repository. +It should be formatted using [GitHub flavored Markdown](https://github.github.com/gfm/) to get formatted properly by those systems. + +`README.md` should include: + +- A brief description of the package's purpose. +- Installation information (How do I get it working?) +- Compatibility information (what versions of Plone does it work with?) +- Links to other sources of documentation. +- Links to issue trackers, mailing lists, and other ways to get help. + +### The manual (narrative documentation) + +The manual goes into further depth for people who want to know all about how to use the package. + +It includes topics like: + +- What are its features +- How to use them (in English — not doctests!) +- Information about architecture +- Common gotchas + +The manual should consider various audiences who may need different types of information: + +- End users who use Plone for content editing, but don't manage the site. +- Site administrators who install and configure the package. +- Integrators who need to extend the functionality of the package in code. +- System administrators who need to maintain the server running the software. + +Simple packages with limited functionality can get by with a single page of narrative documentation. +In this case, it's simplest to include it in an extended `README.md`. +Some excellent examples of a single-page README are and . + +If your project is moderately complex, you may want to set up your documentation with multiple pages. +The preferred way to do this is to add Sphinx to your project, and host your docs on [readthedocs.org](https://readthedocs.org), so that it rebuilds the documentation whenever you push to GitHub. +If you do this, your `README.md` must link off site to the documentation. + +### Reference or API documentation + +An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code). +It is meant for random access to remind the reader of how a particular class or method works, rather than for reading in its entirety. + +If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx. + +### Changes or history + +Best practice is to set up [towncrier](https://pypi.org/project/towncrier/) so your package will have a clear and structured history of changes. + +### Licenses + +Information about the open source license used for the package should be placed within the `docs` directory. + +For Plone core packages, this includes `LICENSE.md` and {file}`LICENSE.GPL`. diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md new file mode 100644 index 0000000000..6c505c50ad --- /dev/null +++ b/docs/contributing/core/index.md @@ -0,0 +1,248 @@ +--- +myst: + html_meta: + "description": "Contributing to Plone 6 Core" + "property=og:description": "Contributing to Plone 6 Core" + "property=og:title": "Contributing to Plone 6 Core" + "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct" +--- + +# Contributing to Plone 6 core + +This part describes the process of development in Plone core. +It's primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). + +It expands upon {doc}`/contributing/index` and, where applicable, {doc}`/contributing/first-time`. + +## Version support policy + +If you are fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule) + +## Dependencies + +```{include} ../../volto/contributing/install-operating-system.md +``` + +- {ref}`setup-build-installation-python-label` {SUPPORTED_PYTHON_VERSIONS} +- {ref}`setup-build-installation-gnu-make-label` +- [git](https://help.github.com/articles/set-up-git/) +- [Pillow](https://pypi.org/project/Pillow/). +- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. +- [GCC](https://gcc.gnu.org/) to compile {term}`ZODB`, {term}`Zope` and {term}`lxml`. + +The first step in fixing a bug is getting this [buildout](https://github.com/plone/buildout.coredev) running. +Start with fixing the bug on the latest branch and then [backporting](https://en.wikipedia.org/wiki/Backporting) as necessary. +[GitHub](https://github.com/plone/buildout.coredev/) by default always points to the currently active branch. +Depending on the current development cycle there may exist a future branch. + +At the moment 6.0 is the actively maintained stable branch and 6.1 is the future, currently unstable, active development branch. +More information on switching release branches is below. + +To set up a plone 6 development environment: + +```shell +cd ~/buildouts # or wherever you want to put things +git clone -b 6.1 https://github.com/plone/buildout.coredev ./plone6devel +cd ./plone6devel +./bootstrap.sh +``` + +If you run into issues in this process, please see {doc}`troubleshooting`. + +This will run for a long time if it's your first pull (approximately 20 minutes). +Once that's done pulling down eggs, you can start your new instance with: + +```shell +./bin/instance fg +``` + +or as {term}`WSGI` service with:: + +```shell +./bin/wsgi +``` + +To login, the defaults are: + +- username: admin +- password: admin + +## Switching branches + +If the bug is specific to one branch or should be [backported](http://en.wikipedia.org/wiki/Backporting), +you can easily switch branches. The first time you get a branch, you must do: + +```shell +git checkout -t origin/6.1 +``` + +This should set up a local 6.1 branch tracking the one on GitHub. +From then on you can do: + +```shell +git checkout 6.1 +``` + +To see what branch you are currently on, + +```shell +git branch +``` + +The line with a * by it will indicate which branch you are currently working on. + +```{important} +Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. +``` + +## Jenkins and mr.roboto + +Plone has a continuous integration ({term}`CI`) setup and follows CI rules. + +When you push a change to any Plone package, the testing/CI package [mr.roboto](https://github.com/plone/mr.roboto) starts running all the tests to make sure that you don't break anything. +For each Plone and Python version it runs two jobs, one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are affected by your change). + +See {doc}`continuous-integration` for more information. + +## Check out packages to fix + +Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. +It can be a little daunting at first to find out which packages cause the bug in question, you can ask in if you need some help. +Once you know which packages you want, pull their source. + +At the base of your buildout, open {file}`checkouts.cfg` and add your package if it's not already there: + +```cfg +auto-checkout = + # my modified packages + plone.app.caching + plone.caching + # others + ... +``` + +Then rerun buildout to get the source packages: + +```shell +./bin/buildout +``` + +For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. + +## Testing locally + +To run a test for the specific module you modify: + +```shell +./bin/test -m plone.app.caching +``` + +These should all run without error. +Please don't check in anything that doesn't succeed! +Now write a test case for the bug you are fixing, and make sure everything is running as it should. + +After the module level tests run with your change, please make sure other modules aren't affected by the change by running the full suite, including robot-tests (remove the `--all` to run without robot tests): + +```shell +./bin/test --all +``` + +```{note} +Tests take a long time to run. +Once you have enough experience in doing bugfixes, +you may let jenkins do this part for you. +More on that below. +``` + +## Updating `CHANGES.rst` and `checkouts.cfg` + +Once all the tests run locally on your machine, you are **ALMOST** ready to commit the changes. +You must perform a couple housekeeping chores before moving on. + +You need to create a change note of what has been modified. +This change note will be collated for the next Plone release and is important for integrators and developers to be able to see what they will get if they upgrade. + +Most packages are using [towncrier](https://pypi.org/project/towncrier/). +If that is the case, there will be a directory "news" in the package. Please follow the Towncrier format and put a note in that directory. + +For packages that haven't switched to using Towncrier, edit {file}`CHANGES.rst` (or {file}`CHANGES.txt`, or {file}`HISTORY.txt`) in each package you have modified and add a summary of the change. New changelog entries should be added at the top of {file}`CHANGES.rst`. + +Most importantly, if you didn't do it earlier, edit the file {file}`checkouts.cfg` in the buildout directory, and add your changes package to the `auto-checkout` list. +This lets the release manager know that the package has been updated, so that when the next release of Plone is cut, a new egg will be released, and Plone will need to pin to the next version of that package. +In other words, this is how your fix becomes an egg! + +Note that there is a section separator called "# Test Fixes Only". +Make sure your egg is above that line, else your egg probably won't get made quickly. +This tells the release manager that any eggs below this line have tests that are updated, but no code changes. + +Modifying the file {file}`checkouts.cfg` also triggers the buildbot, [jenkins](https://jenkins.plone.org/), to pull in the egg and run all the tests against the changes you just made. + +If your bug fix is in more than one release, for example 6.1 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg` in both branches. + +## Commits and pull requests + +Review the following checklist: + +- Did you fix the original bug? +- Is your code consistently formatted? You can use the [Plone Meta](https://github.com/plone/meta) project to set up your development environment to be consistent with Plone community agreed best practices. +- Did you remove any extra code and lingering {term}`pdb` statements? +- Did you write a test case for that bug? +- DO all test cases for the modules and Plone pass? +- Did you write an update note (using Towncrier or via {file}`CHANGES.rst`) in each package you changed? +- Did you add your changed packages to {file}`checkouts.cfg`? + +If you answered *Yes* to all, then you are ready to push your changes! +A couple of quick reminders: + +- Never commit directly to the development branch. Create a `pull request` (more on that below). +- Please try to make one change per commit. + If you are fixing three bugs, make three commits. + That way, it's easier to see what was done when, and easier to roll back any changes if necessary. + If you want to make large changes cleaning up whitespace or renaming variables, it's especially important to do so in a separate commit for this reason. + +## Branching and pull requests + +You should create a branch of whatever packages you are updating, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. + +Take the `plone.app.caching` example. +After checking it out with `mr.developer`, create your own branch with: + +```shell +cd src/plone.app.caching +git checkout -b my_descriptive_branch_name +``` + +When you are ready to push your fix, push to a remote branch with: + +```shell +git push origin my_descriptive_branch_name +``` + +This will make a remote branch in GitHub. +Navigate to this branch in the GitHub user interface, and on the top right, there will be a button that says {guilabel}`Pull Request`. +This will turn your request into a pull request on the main branch. +There are people who look once a week or more for pending pull requests and will confirm whether it's a good fix, and give you feedback where necessary. +The reviewers are informal and nice, so don't worry. +They are there to help! +If you want immediate feedback, visit with the pull request link and ask for a review. + +## Finalize issues + +If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. +There is no automatic integration with GitHub yet so it's a nice way to track changes. +It also lets the reporter know that you care. + +## Additional material + +```{toctree} +:maxdepth: 1 + +continuous-integration +mrdeveloper +documentation +troubleshooting +plips +plip-review +package-dependencies +release +``` diff --git a/docs/contributing/core/mrdeveloper.md b/docs/contributing/core/mrdeveloper.md new file mode 100644 index 0000000000..ce14a624dd --- /dev/null +++ b/docs/contributing/core/mrdeveloper.md @@ -0,0 +1,36 @@ +--- +myst: + html_meta: + "description": "mr.developer" + "property=og:description": "mr.developer" + "property=og:title": "mr.developer" + "keywords": "mr.developer" +--- + +# `mr.developer` + +This buildout uses `mr.developer` to manage package development. +See [mr.developer on pypi](https://pypi.org/project/mr.developer/) for more information, or run `bin/develop help` for a list of available commands. + +The most common workflow to get all the latest updates is: + +```shell +git pull +bin/develop rebuild +``` + +This will get you the latest `coredev` configuration, checkout and update all packages via git in src, and run buildout to configure the whole thing. + +From time to time you can check if some old cruft has accumulated: + +```shell +bin/develop status +``` + +If this prints any lines with a question mark in front, you can cleanup by: + +```shell +bin/develop purge +``` + +This will remove packages from {file}`src/` which are no longer needed, as they have been replaced by proper egg releases of these packages. diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md new file mode 100644 index 0000000000..d2270a3955 --- /dev/null +++ b/docs/contributing/core/package-dependencies.md @@ -0,0 +1,350 @@ +--- +myst: + html_meta: + "description": "This chapter describes the architecture of Plone's packages and dependencies." + "property=og:description": "This chapter describes the architecture of Plone's packages and dependencies." + "property=og:title": "Architecture: packages and dependecies" + "keywords": "Architecture, packages, dependecies, Plone" +--- + +# Architecture: packages and dependecies + +This chapter describes the architecture of Plone's packages and dependencies. + +## Motivation + +Plone has over the years developed many indirections in its packages and dependencies. +The goal in the long run is to untangle them and get a simple dependency graph. +This document shows the current state, as orientation. + +## Overview + +There are multiple level of dependencies: + +- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) +- Python level (imports) +- ZCML level (includes) +- testing (need for layers, such as functional testing) + +At some point there were circular dependencies at the package level. +This was solved. + +Nevertheless there is indirection on all other levels. +Since Plone consists of a lot of packages, it is complex to untangle those. + +## Mental model + +A base mental model for how Plone is organized in Plone 6 is shown in the following diagram: + +```{mermaid} +block-beta + columns 1 + + Plone["Plone
the integraton of both distributions in one release"] + space + Distributions + block:dist + plone.volto + plone.classic + end + space + block:core + coreaddons["Core addons"] + coreapi["Core APIs"] + end + space + cmfplone["Products.CMFPlone"] + + space:2 + + block:layer + ploneapp["Most of plone.app.* namespace"] + otherlay["Various other packages"] + end + +space + + plonebase["plone.base"] + space + foundations["The Foundations"] + space:3 + block:foundationcomponents + ploneworld["Plone world"] + zopeeco["Zope ecosystem"] + zopecore["Zope core"] + libraries["Libraries"] + end + Plone --> Distributions + dist --> core + cmfplone --> layer + core --> cmfplone + layer --> plonebase + plonebase --> foundations + + style cmfplone fill:#ff0 + style plonebase fill:#ff0 + +``` + +As a rough model there are two packages as dividing lines: + +1. `Products.CMFPlone` +2. `plone.base` + +## Packages in detail + +Looking deeper into those, there are more sub-dividers, but first group all into the three groups: + +### Above `Products.CMFPlone` + +- Plone +- plone.api +- plone.app.iterate +- plone.app.upgrade +- plone.restapi +- plone.volto +- Products.CMFPlacefulWorkflow + +### Between `Products.CMFPlone` and `plone.base` + +- collective.monkeypatcher +- plone.app.caching +- plone.app.content +- plone.app.contentlisting +- plone.app.contentmenu +- plone.app.contentrules +- plone.app.contenttypes +- plone.app.customerize +- plone.app.dexterity +- plone.app.discussion +- plone.app.event +- plone.app.i18n +- plone.app.intid +- plone.app.layout +- plone.app.linkintegrity +- plone.app.locales +- plone.app.lockingbehavior +- plone.app.multilingual +- plone.app.portlets +- plone.app.querystring +- plone.app.redirector +- plone.app.registry +- plone.app.relationfield +- plone.app.textfield +- plone.app.theming +- plone.app.users +- plone.app.uuid +- plone.app.versioningbehavior +- plone.app.viewletmanager +- plone.app.vocabularies +- plone.app.widgets +- plone.app.workflow +- plone.app.z3cform +- plone.browserlayer +- plone.cachepurging +- plone.contentrules +- plone.formwidget.namedfile +- plone.formwidget.recurrence +- plone.i18n +- plone.namedfile +- plone.outputfilters +- plone.portlet.collection +- plone.portlet.static +- plone.portlets +- plone.protect +- plone.resourceeditor +- plone.rfc822 +- plone.schemaeditor +- plone.session +- plone.staticresources +- plone.stringinterp +- plone.theme +- plonetheme.barceloneta +- Products.isurlinportal + +### The foundation below `plone.base` + +#### Plone world + +- borg.localrole +- plone.alterego +- plone.autoform +- plone.autoinclude +- plone.batching +- plone.behavior +- plone.caching +- plone.dexterity +- plone.event +- plone.folder +- plone.indexer +- plone.intelligenttext +- plone.keyring +- plone.locking +- plone.memoize +- plone.registry +- plone.resource +- plone.rest +- plone.scale +- plone.schema +- plone.subrequest +- plone.supermodel +- plone.transformchain +- plone.uuid +- plone.z3cform +- Products.DateRecurringIndex +- Products.ExtendedPathIndex +- Products.MimetypesRegistry +- Products.PlonePAS +- Products.PortalTransforms +- Products.statusmessages + +#### Zope ecosystem + +- Chameleon +- diazo +- five.customerize +- five.intid +- five.localsitemanager +- icalendar +- Products.CMFCore +- Products.CMFDiffTool +- Products.CMFDynamicViewFTI +- Products.CMFEditions +- Products.CMFUid +- Products.DCWorkflow +- Products.ExternalMethod +- Products.GenericSetup +- Products.MailHost +- Products.PluggableAuthService +- Products.PluginRegistry +- Products.PythonScripts +- Products.Sessions +- Products.SiteErrorLog +- Products.StandardCacheManagers +- Products.ZopeVersionControl +- repoze.xmliter +- webresource +- z3c.caching +- z3c.form +- z3c.formwidget.query +- z3c.objpath +- z3c.pt +- z3c.relationfield +- z3c.zcmlhook +- zc.recipe.egg +- zc.relation +- zodbverify +- zope.copy +- zope.intid +- zope.keyreference + +#### Zope core + +- AccessControl +- Acquisition +- AuthEncoding +- beautifulsoup4 +- BTrees +- DateTime +- DocumentTemplate +- ExtensionClass +- Missing +- MultiMapping +- Persistence +- persistent +- Products.BTreeFolder2 +- Products.ZCatalog +- Record +- RestrictedPython +- transaction +- zc.lockfile +- ZConfig +- zdaemon +- ZEO +- zExceptions +- ZODB +- ZODB3 +- zodbpickle +- Zope +- zope.annotation +- zope.app.locales +- zope.browser +- zope.browsermenu +- zope.browserpage +- zope.browserresource +- zope.cachedescriptors +- zope.component +- zope.componentvocabulary +- zope.configuration +- zope.container +- zope.contentprovider +- zope.contenttype +- zope.datetime +- zope.deferredimport +- zope.deprecation +- zope.dottedname +- zope.event +- zope.exceptions +- zope.filerepresentation +- zope.globalrequest +- zope.hookable +- zope.i18n +- zope.i18nmessageid +- zope.interface +- zope.lifecycleevent +- zope.location +- zope.pagetemplate +- zope.processlifetime +- zope.proxy +- zope.ptresource +- zope.publisher +- zope.ramcache +- zope.schema +- zope.security +- zope.sendmail +- zope.sequencesort +- zope.site +- zope.size +- zope.structuredtext +- zope.tal +- zope.tales +- zope.testbrowser +- zope.testing +- zope.traversing +- zope.viewlet +- Zope2 + +#### Libraries + +- attrs +- cffi +- cssselect +- decorator +- docutils +- feedparser +- future +- importlib_metadata +- jsonschema +- Markdown +- multipart +- Paste +- PasteDeploy +- piexif +- Pillow +- pycparser +- PyJWT +- pyrsistent +- python_dotenv +- python_gettext +- requests +- roman +- sgmllib3k +- simplejson +- soupsieve +- Unidecode +- urllib3 +- waitress +- WebOb +- WebTest +- WSGIProxy2 +- zipp diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md new file mode 100644 index 0000000000..670838c932 --- /dev/null +++ b/docs/contributing/core/plip-review.md @@ -0,0 +1,101 @@ +--- +myst: + html_meta: + "description": "PLIP review" + "property=og:description": "PLIP review" + "property=og:title": "PLIP review" + "keywords": "PLIP, review, Plone Improvement Proposal, Plone" +--- + +# PLIP review + +A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. + +## Expectations + +A good PLIP review takes about four hours. +Please plan accordingly. + +When you are done, if you have access to core, commit the review to the `plips` folder of [buildout.coredev](https://github.com/plone/buildout.coredev), and reference the PLIP in your commit message. +If you do not have access, attach your review to the PLIP ticket itself. + +## Setting up the environment + +Follow the instructions in {doc}`index`. +You will need to checkout the branch to which the PLIP is assigned. +Instead of running the buildout with the default buildout file, you will run the configuration specific to that PLIP: + +```shell +./bin/buildout -c plips/plip-XXXX.cfg +``` + +## Functionality review + +This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. + +### General + +- Does the PLIP actually do what the implementers proposed? + Are there incomplete variations? +- Were there any errors running buildout? + Did the migration(s) work? +- Do error and status messages make sense? + Are they properly internationalized? +- Are there any performance considerations? + Has the implementer addressed them, if so? +- For changes in the UI, are they accessible for people using assisted technologies? + +### Bugs + +- Are there any bugs? + Nothing is too big nor small. +- Do fields handle wacky, incomplete or harmful data? + How about strings in date fields, or nulls in required? +- Is validation up to snuff and sensical? + Is it too restrictive or not restrictive enough? + +### Usability Issues + +- Is the implementation usable? +- How will novice end users respond to the change? +- Does this PLIP need a usability review? + If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. +- Is the PLIP consistent with the rest of Plone? + For example, if there is control panel configuration, does the new form fit in with the rest of the panels? +- Does everything flow nicely for novice and advanced users? + Is there any workflow that feels odd? +- Are there any new permissions and do they work properly? + Does their role assignment make sense? + +### Documentation Issues + +- Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? +- Is the change itself properly documented? + +Report bugs or issues on GitHub as you would for any Plone bug. +Reference the PLIP in the bug, assign to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. +This way the implementer can find help if they need it. +Also set a priority for the ticket. +The PLIP will not be merged until all blockers and critical bugs are fixed. + +### Code Review + +#### Python + +- Is this code maintainable? +- Is the code properly documented? +- Does the code adhere to Plone best practices for formatting? +- Are they importing deprecated modules? + +#### JavaScript + +- Does the JavaScript meet Plone's set of JavaScript standards? +- Does the JavaScript work in all currently supported browsers? + Is it performant? + +#### ME/TAL + +- Does the PLIP use views appropriately, avoiding too much logic? +- Is there any code in a loop that could potentially be a performance issue? +- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? +- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md new file mode 100644 index 0000000000..7f7b766d9f --- /dev/null +++ b/docs/contributing/core/plips.md @@ -0,0 +1,276 @@ +--- +myst: + html_meta: + "description": "Plone Improvement Proposals (PLIPs)" + "property=og:description": "Plone Improvement Proposals (PLIPs)" + "property=og:title": "Plone Improvement Proposals (PLIPs)" + "keywords": "Plone Improvement Proposal, PLIP)" +--- + +# Plone Improvement Proposals (PLIPs) + +A {term}`PLIP` is a Plone Improvement Proposal. + +It is a change to a Plone package that would affect everyone. +PLIPs go through a different process than bug fixes because of their broad reach. +The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. + +## Frequently asked questions about PLIPs + +This section provides detailed answers to common questions about PLIPs. + +### PLIP or bugfix? + +In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. +When in doubt, submit it as a PLIP. +The Framework Team will reclassify it if your proposal falls below the threshold. +If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. +The key point here is that each change must be documented, allowing it to be tracked and understood. + +### Who can submit PLIPs? + +Anyone who has signed a Plone Contributor Agreement can work on a PLIP. + +You do not have to be the most amazing coder in the world to submit a PLIP. +The Framework Team is happy to help you at any point in the process. + +Submitting a PLIP can be a great learning process. + +When the PLIP is accepted, a Framework Team member will "champion" your PLIP and follow up to its completion. + +PLIPs are not just for code experts. +If you have ideas on new interactions or UI your ideas are more than welcome. + +The community will help you pair up with implementers if needed. + +### What is a PLIP champion? + +When you submit your PLIP and it is approved, a Framework Team member will take on the role of champion for that PLIP. + +They are there to help you through completion, answer questions and provide guidance. + +A champion fulfills the following tasks: + +- Answer any questions the PLIP implementer has, technical or otherwise. +- Encourage the PLIP author by giving feedback and encouragement. +- Keep the implementer aware of timelines, and push to get things done on time. +- Assist with finding additional help when needed to complete the implementation in a timely matter. + +Keep in mind that champions are volunteers as well, and have other tasks in life. +That means you will have to play an active role in asking for help or guidance. + +### Can I get involved in other ways? + +If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. +Ask one of the Framework Team members what PLIPs are available for review, or check the status of PLIPs at the [GitHub issues](https://github.com/plone/Products.CMFPlone/issues) page +for [Products.CMFPlone](https://github.com/Plone/Products.CMFPlone) +for [issues tagged with "03 type: feature (plip)"](https://github.com/plone/Products.CMFPlone/labels/03%20type%3A%20feature%20%28plip%29). + +Make sure to let the community know you intend to review the PLIP by communicating that to the [Framework Team](https://community.plone.org/c/development/framework-team). + +Then, follow the instructions for {doc}`reviewing a PLIP `. + +Thank you in advance! + +### When can I submit a PLIP? + +Today, tomorrow, any time! + +After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. + +### When is the PLIP due? + +**Summary: As soon as you get it done.** + +Ideally, a PLIP should be completed for the release to which it's assigned. +Sometimes life gets in the way, and a PLIP may have to be re-assigned to the following release. + +In general, PLIPs shouldn't take more than a year, otherwise they should be closed. A new PLIP can follow up if there is more capacity to see it through. + +### What happens if your PLIP is not accepted? + +If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. +It is often the case that there are competing implementations, and the community wants to see it vetted as an add-on before "blessing" a particular implementation. + +## Process Overview + +1. Submit a PLIP at any time. +2. PLIP is approved for inclusion into core for a given release. +3. Developer implements PLIP (code, tests, documentation). +4. PLIP is submitted for review by developer. +5. Framework Team reviews the PLIP and gives feedback. +6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. +7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. +8. PLIP is approved for merge. + In rare circumstances, a PLIP will be rejected. + This is usually the result of the developer not responding to feedback or dropping out of the process. + Hang in there! +9. After all other PLIPs are merged, a release is cut. + Standby for bugs! + +(how-to-submit-a-plip)= + +## How to submit a PLIP + +Whether you want to update the default theme, or rip out a piece of architecture, major changes should go through the PLIP process. +If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team). + +A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues/new) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. + +To get started, open a new issue. +The issue will be prefilled with headings and comments for a bug or a PLIP. +Remove the bug part. +Fill in all applicable fields. +After submitting, select the tag `03 type: feature (plip)` for the issues. + +When writing a PLIP, be as specific and to-the-point as you can. +Remember your audience. +To get support for your proposal, people will have to be able to read it! + +A good PLIP is sufficiently clear for a knowledgeable Plone user to understand the proposed changes, and sufficiently detailed for the release manager and other developers to understand the full impact the proposal would have on the code base. + +You don't have to list every line of code that needs to be changed, but you should also give an indication that you have some idea of how the change can be feasibly implemented. + +After your PLIP is written, solicit feedback on your idea on the [Plone Community Forum](https://community.plone.org/). +In this vetting process, you want to make sure that the change won't adversely affect other people on accident. +Others may be able to point out risks or even offer up better or existing solutions. + +Please note a few things: + +- It is very rare that the "Risks" section will be empty or none. +- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. +- The seconder field is REQUIRED. + +The PLIP will be sent back to you if it is not filled in. +Currently, this is just someone else who thinks your PLIP is a good idea, a +1. + +In the near future, the seconder should either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. + +### Evaluating PLIPs + +After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. +If the PLIP is not accepted, please don't be discouraged! + +Most PLIPs first start as an add-on, if possible, to make sure it works in practice. + +All communication with you occurs on the PLIP issue itself. +Please keep your eyes and inbox open for changes. + +These are the criteria by which the framework team will review your work: + +- What is the size and status of the work needed to be done? +- Is it already an add-on and well established? +- Is this idea well baked and expressed clearly? +- Does the work proposed belong in Plone now, or in the future? +- Is this PLIP more appropriate as a qualified add-on? +- Is this PLIP too risky? + +See the {doc}`plip-review` page for more information. + +## Implementing your PLIP + +You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. + +### General Rules + +- Any new packages must be in a branch in the `plone` namespace in GitHub. + You don't have to develop there, but it must be there when submitted. + Use branches off of the repositories under the Plone GitHub organization, see below. +- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. +- Any new code must: + + - Be {doc}`properly documented `. + - Have clear code. + - Follow current best practices in coding style. The [Plone Meta](https://github.com/plone/meta) project can help you set up your environment. For Volto, follow [this guide](https://6.docs.plone.org/volto/contributing/linting.html). + - [Be tested](https://5.docs.plone.org/develop/testing/index.html). For Volto, follow [this guide](https://6.docs.plone.org/volto/contributing/testing.html) + +```{todo} +Update links from Plone 5 to Plone 6 Documentation, once content is migrated. +See https://github.com/plone/documentation/issues/1330 and other issues. +``` + +### Creating a new PLIP branch + +Create a buildout configuration file for your PLIP in the `plips` folder of {file}`buildout.coredev`. + +Give it a descriptive name, starting with the PLIP number, for example, {file}`plip-1234-widget-frobbing.cfg`. + +The PLIP number is your PLIP's issue number. + +This file will define the branches you're working with in your PLIP, along with other buildout configuration. + +It should look something like the following, such as in a file {file}`plips/plip-1234-widget-frobbing.cfg`. + +```ini +[buildout] +extends = plipbase.cfg +auto-checkout += + plone.somepackage + plone.app.someotherpackage + +[sources] +plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-1234-widget-frobbing +plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-1234-widget-frobbing + +[instance] +eggs += + plone.somepackage + plone.app.someotherpackage +zcml += + plone.somepackage + plone.app.someotherpackage +``` + +Use the same naming convention when you branch existing packages. +You should always branch packages when working on PLIPs. + +### Working on a PLIP + +To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: + +```shell +virtualenv . +./bin/pip install -r requirements.txt +./bin/buildout -c plips/plip-1234-widget-frobbing.cfg +``` + +If you are using a {file}`local.cfg` to extend your PLIP file with some changes that you do not want to commit accidentally, be aware that you need to override some settings from {file}`plipbase.cfg` to avoid some files being created in the {file}`plips` directory or in the directory above the buildout directory. +This is done as shown below. + +```ini +[buildout] +extends = plips/plip-1234-widget-frobbing.cfg +develop-eggs-directory = ./develop-eggs +bin-directory = ./bin +parts-directory = ./parts +sources-dir = ./src +installed = .installed.cfg + +[instance] +var = ./var +``` + +### Finishing up + +Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. +This file should be called {file}`plip__notes.txt`. +This should include, but is not limited to: + +- URLs pointing to all documentation created and updated +- Any concerns and issues still remaining +- Any weird buildout things + +Once you have finished, update your PLIP issue to indicate that it is ready for review. +The Framework Team will assign 2-3 people to review your PLIP. +They will follow the guidelines listed at {doc}`plip-review`. + +After the PLIP has been accepted by the Framework Team and the release managers, you will be asked to merge your work into the main development line. +Merging the PLIP in is not the hardest part, but you must think about it when you develop. + +You'll have to interact with a large number of people to get it all set up. + +The merge may have unintended interactions with other PLIPs coming in. +During the merge phase you must be prepared to help out with all the features and bugs that arise. + +If all went as planned, the next Plone release will carry on with your PLIP in it. +You'll be expected to help out with that feature after it's been released (within reason). diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md new file mode 100644 index 0000000000..f9eba0c43b --- /dev/null +++ b/docs/contributing/core/release.md @@ -0,0 +1,127 @@ +--- +myst: + html_meta: + "description": "Plone release process" + "property=og:description": "Plone release process" + "property=og:title": "Plone release process" + "keywords": "Plone, release, process" +--- + +# Plone release process + +This chapter describes the process to release Plone and its packages. + +## Release process for Plone packages + +To keep the Plone software stack maintainable, the Python egg release process must be automated to a high degree. +This happens by enforcing Python packaging best practices, and then making automated releases using [`zest.releaser`](https://github.com/zestsoftware/zest.releaser/). + +Plone coredev specific features extend on that using [`plone.releaser`](https://github.com/plone/plone.releaser). + +Anyone with necessary PyPI permissions must be able to make a new release by running the `fullrelease` command. +This command includes the following requirements. + +```{note} +All files mentioned in this list may be written in Markdown or reStructuredText and have the appropriate file name suffix. +``` + +- All releases must be hosted on PyPI. +- All versions must be tagged in version control. +- Each package must have a {file}`README` file with links to the version control repository and issue tracker. +- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. +- {file}`CHANGES` must contain release dates. +- {file}`README` and {file}`CHANGES` must be visible on PyPI. +- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. + The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. +- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). + +```{seealso} +[High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). +``` + +## Special packages + +The Plone Release Team releases the core Plone packages. +Several others also have the rights to release individual packages on [PyPI](https://pypi.org/). +If you have those rights on your account, you should feel free to make releases. + +Some packages need special care, or should be done only by specific people, as they know what they are doing. +These are: + +`Products.CMFPlone`, `Plone`, and `plone.app.upgrade` +: Please leave these to the release managers, Eric Steele and Maurits van Rees. + +`plone.app.locales` +: Please leave this to the i18n team lead, Vincent Fretin. + +## Plone core release process checklist + +1. Check Jenkins status. + Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org/). + It should be green, but if it is not, fix the problem first. + +2. Check out `buildout.coredev`. + + ```shell + git clone git@github.com:plone/buildout.coredev.git + cd buildout.coredev + git checkout 6.1 + python bootstrap.py + bin/buildout -c buildout.cfg + ``` + +3. Check packages for updates. + Check all packages for updates, add to or remove from `checkouts.cfg` accordingly. + This script may help: + + ```shell + bin/manage report --interactive + ``` + + This step should not be needed, because we do the check for every single commit, but people may still have forgotten to add a package to the `checkouts.cfg` file. + +4. Check packages individually. + + Use the `bin/fullrelease` script from the core development buildout. + This includes extra checks that we have added in `plone.releaser`. + It guides you through all the next steps. + + 1. Check changelog. + Check if `CHANGES` is up-to-date. + All changes since the last release should be included. + A "Fixes" or "New" header should be included, with the relevant changes under it. + Upgrade notes are best placed here as well. + Compare `git log HEAD...` with `CHANGES`, or from `zest.releaser` use the command `lasttaglog `. + 2. Run [pyroma](https://pypi.org/project/pyroma/). + 3. Run [check-manifest](https://pypi.org/project/check-manifest/). + 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). + 5. Check if the version in `setup.py` is correct and follows our versioning best practice. + 6. Make a release (zest.releaser: `bin/fullrelease`) + 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. + +5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. +6. Update CMFPlone version in `profiles/default/metadata.xml`. +7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. +8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). + + 1. Copy all core packages there. + 2. Possibly make an alpha or beta release of CMFPlone. + 3. Copy the `versions.cfg` file from coredev to there. + +9. Write an email to the Plone developers list announcing a pending release. +10. Update `plone.app.locales` version. +11. Create a unified changelog. + + ```shell + bin/manage changelog + ``` + +12. Make the final release on [dist.plone.org](https://dist.plone.org/) (remove "-pending") +13. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). +14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). +15. Create a release page on [plone.org](https://plone.org/download/releases) +16. Wait for installers to be uploaded to Launchpad, with a link to the [plone.org](https://plone.org/download/releases) release page. +17. Publish release page on [plone.org](https://plone.org). +18. Update plone.org homepage links to point to the new release. +19. Send out announcement to the plone-announce email distribution list. +20. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. diff --git a/docs/contributing/core/troubleshooting.md b/docs/contributing/core/troubleshooting.md new file mode 100644 index 0000000000..7a08cfa170 --- /dev/null +++ b/docs/contributing/core/troubleshooting.md @@ -0,0 +1,55 @@ +--- +myst: + html_meta: + "description": "Troubleshooting development issues in Plone" + "property=og:description": "Troubleshooting development issues in Plone" + "property=og:title": "Troubleshooting development issues in Plone" + "keywords": "Troubleshooting, development issues, Plone" +--- + +# Troubleshooting + +This chapter describes how to troubleshoot development issues in Plone. + +## Buildout issues + +Buildout can be frustrating for those unfamiliar with parsing through error messages. + +These errors are normally a quick fix. + +### Errors running `bootstrap.py` + +You may not even get to running buildout, before you already get an error. +As example: + +```shell + File "/usr/local/lib/python2.6/site-packages/distribute-0.6.13-py2.6.egg/pkg_resources.py", line 556, in resolve + raise VersionConflict(dist,req) # XXX put more info here + pkg_resources.VersionConflict: (zc.buildout 1.5.1 (/usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg), Requirement.parse('zc.buildout==1.5.2')) +``` + +Buildout has noticed that the version of buildout required by the file `bootstrap.py` you are trying to run does not match the version of buildout in your Python library. +In the error above, your system has buildout 1.5.1 installed and the `bootstrap.py` file wants to run with 1.5.2. + +To fix, you have a couple options. +First, you can force buildout to run with the version you already have installed by invoking the version tag. +This tells your Plone `bootstrap.py` file to play nicely with the version that you already have installed. +In the case of the error pasted above, that would be: + +```shell +python bootstrap.py --version=1.5.1 +``` + +The other option is to delete your current egg and force the upgrade. +In the case of the error above, delete the egg the system currently has, for example: + +```shell +rm -rf /usr/local/lib/python3.10/site-packages/zc.buildout-1.5.1-py3.10.egg +``` + +When you rerun bootstrap, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. + +Do one of those and re-run bootstrap. + +One other thing of note is that running bootstrap effectively ties that Python executable and all of its libraries to your buildout. +If you have several Python installs, and want to switch which Python is tied to your buildout, rerun `bootstrap.py` with the new Python (and then rerun buildout). diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 24be3d4ff2..54735e7e71 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -20,7 +20,6 @@ To contribute to any project in Plone, you must follow the policies of the [Plon This chapter covers policies that apply to all Plone projects. Other chapters cover any variations and additional policies for each project. - (contributing-sign-and-return-the-plone-contributor-agreement-label)= ## Sign and return the Plone Contributor Agreement @@ -48,7 +47,6 @@ Sign the Plone Contributor Agreement - [Plone Framework Components Relicensing Policy, Framework Components Available Under a BSD License](https://plone.org/foundation/about/materials/foundation-resolutions/plone-framework-components-relicensing-policy#3b050ad2-361a-46de-b5c6-9b90f8947eb7) ``` - (contributing-code-of-conduct-label)= ## Code of Conduct @@ -56,14 +54,12 @@ Sign the Plone Contributor Agreement The Plone Foundation has published a [Code of Conduct](https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct). All contributors to the Plone Documentation follow the Code of Conduct. - (contributing-first-time-contributors-label)= ## First-time contributors First-time contributors should read and follow our guide {doc}`first-time`. - (contributing-continuous-integration-label)= ## Continuous integration @@ -72,7 +68,6 @@ Plone project repositories use continuous integration (CI) to run tests, ensure Plone uses GitHub Actions, Jenkins, Cypress, Netlify, and other services for CI. All of a project's CI jobs must pass before a contribution may be accepted. - (contributing-change-log-label)= ## Change log entry @@ -93,18 +88,18 @@ When making a change to its documentation, set up, continuous integration, or ot The change log entry's format must be `###.type`, where `###` is the referenced GitHub issue or pull request number, `.` is the literal extension delimiter, and `type` is one of the following strings. -- `breaking` for breaking changes -- `bugfix` for bug fixes -- `documentation` for documentation -- `feature` for new features -- `internal` for internal changes +- `breaking` for breaking changes +- `bugfix` for bug fixes +- `documentation` for documentation +- `feature` for new features +- `internal` for internal changes A package configures the types it allows in a file `towncrier.toml` located at the root of its package directory. The content of this file must include the following. -- A brief message that summarizes the changes in your contribution. -- An attribution to yourself, in the format of `@github_username`. +- A brief message that summarizes the changes in your contribution. +- An attribution to yourself, in the format of `@github_username`. ```{important} These change log entries become narrative documentation. @@ -112,13 +107,13 @@ These change log entries become narrative documentation. You can write good change log entries with the following guidance. -- Use a narrative format, in the past tense, proper English spelling and grammar, and inline markup as needed. -- Write your change log entry for its appropriate audience. - - Most entries should address _users_ of the software. - - An entry for a change to a public API should address _developers_. -- If you fix a bug, write what was broken and is now fixed. -- If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it. -- Refer to narrative documentation as needed. +- Use a narrative format, in the past tense, proper English spelling and grammar, and inline markup as needed. +- Write your change log entry for its appropriate audience. + - Most entries should address _users_ of the software. + - An entry for a change to a public API should address _developers_. +- If you fix a bug, write what was broken and is now fixed. +- If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it. +- Refer to narrative documentation as needed. The following text is an example of a good change log entry, placed inside {file}`/news/4470.documentation`. @@ -132,7 +127,6 @@ The following would be a poor change log entry. Fix #123456 by chaning config of additionalToolbarComponents [did_not_read_this_guide] ``` - (contributing-project-configuration-files-label)= ## Project configuration files @@ -141,7 +135,6 @@ To standarize the developer experience across packages, a configuration tool is See the [tool documentation](https://github.com/plone/meta) for more information. - (contributing-specific-contribution-policies-for-projects-label)= ## Specific contribution policies of projects @@ -171,7 +164,6 @@ Volto : Plone 6 default frontend. See {doc}`../volto/contributing/index`. - (contributing-releases-label)= ## Releases @@ -182,7 +174,6 @@ We use [`zest.releaser`](https://zestreleaser.readthedocs.io/en/latest/) for rel We use [`release-it`](https://github.com/release-it/release-it) for releasing the Node.js packages used in Plone, including {doc}`Volto ` and the [Classic UI mockup](https://github.com/plone/mockup). - ```{toctree} --- caption: Contributing @@ -192,6 +183,7 @@ hidden: true first-time documentation/index +core/index plone-api plone-restapi volto diff --git a/docs/glossary.md b/docs/glossary.md index 4e161d3177..bf30a43de4 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -77,7 +77,7 @@ pipx pyenv Python version management. - [pyenv](https://github.com/pyenv/pyenv) lets you easily switch between multiple versions of Python. + [pyenv](https://github.com/pyenv/pyenv) lets you easily switch between multiple versions of Python. pm2 [PM2](https://pm2.keymetrics.io/) is a daemon process manager. @@ -470,6 +470,10 @@ language tag - W3C Working Draft [Language Tags and Locale Identifiers for the World Wide Web](https://www.w3.org/TR/ltli/) ``` +lxml + A library used for processing XML and HTML with Python. It is a binding for the libxml2 and libxslt C libraries. + See https://lxml.de/ + gettext UNIX standard software translation tool. See https://www.gnu.org/software/gettext/. @@ -673,6 +677,9 @@ UID UID is an acronym meaning "unique identifier". A UID is an identifier that is guaranteed to be unique among all identifiers used for those objects and for a specific purpose. +pdb + The Python Debugger module is an interactive source code debugger for Python programs. See https://docs.python.org/3/library/pdb.html + integer identifier intid In Plone, an integer identifier, or intid, is used to uniquely identify content objects within a Plone site. @@ -741,7 +748,7 @@ Plone frontend TLS Transport Layer Security Transport Layer Security (TLS) is a cryptographic protocol designed to provide communications security over a computer network. - + ```{seealso} [Transport Layer Security](https://developer.mozilla.org/en-US/docs/Web/Security/Transport_Layer_Security) article from MDN. ``` diff --git a/requirements.txt b/requirements.txt index a6c516054c..a0d60d48fa 100644 --- a/requirements.txt +++ b/requirements.txt @@ -23,4 +23,5 @@ sphinxcontrib-qthelp==1.0.3 # https://github.com/plone/documentation/issues/160 sphinxcontrib-serializinghtml==1.1.5 # https://github.com/plone/documentation/issues/1604 sphinxcontrib-video sphinxext-opengraph +sphinxcontrib.mermaid==0.9.2 vale==2.30.0 diff --git a/styles/Vocab/Plone/accept.txt b/styles/Vocab/Plone/accept.txt index c93207b679..15b0ecf039 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/Vocab/Plone/accept.txt @@ -8,8 +8,10 @@ accessor APIs [Aa]sync [Bb]ackend +backport(ed|ing) Barceloneta [Bb]oolean +bugfix buildout cacheable doctest @@ -17,11 +19,14 @@ folderish fieldset getter JavaScript +[Jj]enkins jQuery +libxslt Mockup npm nvm Pastanaga +PLIP(s) Plone pluggab(le|ility) programatically @@ -34,6 +39,7 @@ RichText Sass Schuko subfolder +[Tt]owncrier transpile[dr]{0,1} unregister UUID From 83b708f7ad337fd5af33508946a1fc446b99caa1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 19 Jun 2024 00:06:39 -0700 Subject: [PATCH 02/69] Revert whitespace changes and use naked URLs (< and > are not required with a MyST extension we use), thus simplifying the diff review against `6.0`. --- coredev/agreement.md | 13 +- coredev/continous-integration.md | 9 + coredev/contributors_agreement_explained.md | 16 +- coredev/documentation.md | 36 +- coredev/getting-started-with-development.md | 88 ++-- coredev/git.md | 9 +- coredev/guidelines.md | 31 +- coredev/index.md | 5 +- coredev/mrdeveloper.md | 2 +- coredev/packages-dependencies.md | 491 ++++++++++---------- coredev/plip-review.md | 56 ++- coredev/plips.md | 80 ++-- coredev/release.md | 67 +-- coredev/roboto.md | 21 +- coredev/troubleshooting.md | 11 + 15 files changed, 512 insertions(+), 423 deletions(-) diff --git a/coredev/agreement.md b/coredev/agreement.md index 53b5bd6f8d..a95b9a8cfe 100644 --- a/coredev/agreement.md +++ b/coredev/agreement.md @@ -23,19 +23,19 @@ Sending in a contributors agreement does not guarantee your commit access to the We ask that before requesting core access you familiarize yourself a little with the community since they will help you get ramped up: -- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. +- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. -- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). +- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). There are plenty of opportunities to meet the community and start contributing through various coding sessions, either in person or on the web. You may even be able to get immediate core access at a conference if you are flexing your mad coding skills and the right people are attending. -- Get your feet wet by contributing to the [collective](https://collective.github.io/). +- Get your feet wet by contributing to the [collective](https://collective.github.io/). Don't worry about getting it perfect or asking for help. This way you get to know us and we improve our code together as a community. -- **Patches:** Historically we encouraged people to submit patches to the ticket collector. +- **Patches:** Historically we encouraged people to submit patches to the ticket collector. These tickets are usually ignored forever. Technically, for us to accept your patch, you must sign the contributors agreement. If you want to contribute fixes, please just sign the agreement and go through the standard GitHub pull request process described below until you feel comfortable to bypass review. @@ -43,7 +43,7 @@ We ask that before requesting core access you familiarize yourself a little with Once you have familiarized yourself with the community and you are excited to contribute to the core: -- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . +- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . This offers both copyright protection and ensures that the Plone Foundation is able to exercise some control over the codebase, ensuring it is not appropriated for someone's unethical purposes. For questions about why the agreement is required, please see [About the Plone Contributor Agreement ](https://plone.org/foundation/contributors-agreement). @@ -54,6 +54,7 @@ A common way to start contributing is to participate in a [Plone sprint](https:/ **Welcome to the Plone community!** + ## Dealing with pull requests on GitHub Before we can merge a pull request, we must ensure that the author has signed the Plone Contributor Agreement. @@ -61,6 +62,6 @@ Before we can merge a pull request, we must ensure that the author has signed th If they're listed in either the [Developers](https://github.com/orgs/plone/teams/developers/members) or [Contributors](https://github.com/orgs/plone/teams/contributors/members) team, the author has signed the Plone Contributor Agreement, so we can go ahead and merge. If they aren't listed there, they may have signed and returned the Plone Contributor Agreement, but they were not yet added to a team. -You can ask to verify. +You can ask agreements@plone.org to verify. Pull requests without a signed Plone Contributor Agreement can only be merged in trivial cases, and only by the release manager. diff --git a/coredev/continous-integration.md b/coredev/continous-integration.md index 3f225f7f24..49eb23d355 100644 --- a/coredev/continous-integration.md +++ b/coredev/continous-integration.md @@ -19,6 +19,7 @@ Build breakages are a normal and expected part of the development process. Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. Though, there are some essential rules that needs to be followed in order to achieve a stable build. + ## 1) Don't check in on a broken build Do not make things more complicated for the developer who is responsible for breaking the build. @@ -37,6 +38,7 @@ If this is the case, there is no way around breaking a single build for a certai In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. ``` + ## 2) Always run all commit tests locally before committing Following this practice ensures the build stays green, and other developers can continue to work without breaking the first rule. @@ -48,28 +50,33 @@ Furthermore, a common source of errors on check-in is to forget to add some file If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system. + ## 3) Wait for commit tests to pass before moving on Always monitor the build's progress, and fix the problem right away if it fails. You have a far better chance of fixing the build, if you just introduced a regression than later. Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours. + ## 4) Never go home on a broken build Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially stops all other developers from working on it. Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. It will prevent all the other developers to stop working on the build or fixing the errors that you introduced. + ## 5) Always be prepared to revert to the previous revision In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. + ## 6) Time-box fixing before reverting When the build breaks on check-in, try to fix it for ten minutes. If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. This way you will allow other developers to continue to work. + ## 7) Don't comment out failing tests Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. @@ -80,6 +87,7 @@ This means that we either caused a regression, made assumptions that are no long You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). + ## 8) Take responsibility for all breakages that result from your changes If you commit a change and all the tests you wrote pass, but others break, the build is still broken. @@ -93,6 +101,7 @@ If you think you hit such a test, try to fix it (better) or re-run the Jenkins j In any case the developer who made the commit is responsible to make it pass. + ## Further Reading Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community. diff --git a/coredev/contributors_agreement_explained.md b/coredev/contributors_agreement_explained.md index 2915b5e61f..ef04222b0b 100644 --- a/coredev/contributors_agreement_explained.md +++ b/coredev/contributors_agreement_explained.md @@ -17,7 +17,8 @@ Prospective contributors to the Plone code base are required to sign a contribut This document explains the purposes of this, along with questions and answers about what this means. -The Plone Contributor's Agreement can be found at . +The Plone Contributor's Agreement can be found at https://plone.org/foundation/contributors-agreement. + ## About the Plone Contributor Agreement @@ -26,9 +27,10 @@ Prior to the Foundation, the intellectual property of Plone was jointly held by The community members who formed the Foundation felt that having the Foundation hold these rights provides several benefits: -1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. -2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. -3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. +1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. +2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. +3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. + ## Questions and answers @@ -92,7 +94,7 @@ How much would a non-GPL version of Plone cost? > Despite this, though, many large and excellent contributions—such as Archetypes—have been made, and the Foundation hopes that companies will continue to do so. > In any event, a company that purchases a non-GPL license (should such ever become available) is contributing financial resources to our community, which can be used to further develop, market, and protect the GPL version of Plone. -- -- -- +- https://plone.org/foundation/contributors-agreement/agreement.pdf +- https://github.com/collective +- https://github.com/plone - [Policy for Contributor Agreements and patches](https://plone.org/foundation/materials/foundation-resolutions/patch-policy-052011) diff --git a/coredev/documentation.md b/coredev/documentation.md index bbaec73bcb..bebf84e090 100644 --- a/coredev/documentation.md +++ b/coredev/documentation.md @@ -16,12 +16,14 @@ For general guidance for contributing documentation, see {doc}`contributing/inde For documentation authors, see {doc}`contributing/authors`. + ## Documentation of Plone -The comprehensive resource for Plone documentation is . +The comprehensive resource for Plone documentation is https://6.docs.plone.org/. The documentation repository is on [GitHub](https://github.com/plone/documentation). Information for how to contribute to documentation can be found at {doc}`contributing/index`. + ## Documenting a package At the very least, your package should include the following forms of documentation. @@ -34,11 +36,12 @@ It should be formatted using [GitHub flavored Markdown](https://github.github.co `README.md` should include: -- A brief description of the package's purpose. -- Installation information (How do I get it working?) -- Compatibility information (what versions of Plone does it work with?) -- Links to other sources of documentation. -- Links to issue trackers, mailing lists, and other ways to get help. +- A brief description of the package's purpose. +- Installation information (How do I get it working?) +- Compatibility information (what versions of Plone does it work with?) +- Links to other sources of documentation. +- Links to issue trackers, mailing lists, and other ways to get help. + ### The manual (narrative documentation) @@ -46,26 +49,27 @@ The manual goes into further depth for people who want to know all about how to It includes topics like: -- What are its features -- How to use them (in English—not doctests!) -- Information about architecture -- Common gotchas +- What are its features +- How to use them (in English—not doctests!) +- Information about architecture +- Common gotchas The manual should consider various audiences who may need different types of information: -- End users who use Plone for content editing, but don't manage the site. -- Site administrators who install and configure the package. -- Integrators who need to extend the functionality of the package in code. -- System administrators who need to maintain the server running the software. +- End users who use Plone for content editing, but don't manage the site. +- Site administrators who install and configure the package. +- Integrators who need to extend the functionality of the package in code. +- System administrators who need to maintain the server running the software. Simple packages with limited functionality can get by with a single page of narrative documentation. In this case, it's simplest to include it in an extended `README.md`. -Some excellent examples of a single-page README are and . +Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching. If your project is moderately complex, you may want to set up your documentation with multiple pages. The preferred way to do this is to add Sphinx to your project, and host your docs on readthedocs.org, so that it rebuilds the documentation whenever you push to GitHub. If you do this, your `README.md` must link off site to the documentation. + ### Reference or API documentation An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code). @@ -73,6 +77,7 @@ It is meant for random access to remind the reader of how a particular class or If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx. + ### Changes or history ```{todo} @@ -100,6 +105,7 @@ See for a fu If a change was related to a bug in the issue tracker, the changelog entry should include a link to that issue. + ### Licenses Information about the open source license used for the package should be placed within the `docs` directory. diff --git a/coredev/getting-started-with-development.md b/coredev/getting-started-with-development.md index 109b4a594e..003e6a7f28 100644 --- a/coredev/getting-started-with-development.md +++ b/coredev/getting-started-with-development.md @@ -16,19 +16,22 @@ Needs updating to Plone6, but contains useful info This document assumes you want to run the current latest Plone source, fix a bug in Plone, or test an add-on in the context of the latest code, and will detail the full process. For how to write Plone Improvement Proposals (PLIPs), read {doc}`plips`. + ## Version support policy If you are triaging or fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule#91815aec-0513-40e0-a804-55ea787a8c68). + ## Dependencies -- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). -- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). -- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). +- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). +- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). +- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). You can do this through the App Store or registering through the Apple Developer Program. -- [Pillow](https://pypi.org/project/Pillow/). -- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. +- [Pillow](https://pypi.org/project/Pillow/). +- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. +- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. + (setup-development-environment)= @@ -67,8 +70,9 @@ or as a WSGI service with: To login, the defaults are: -- username: admin -- password: admin +- username: admin +- password: admin + ## Switching branches @@ -98,6 +102,7 @@ The line with a `*` by it will indicate the branch on which you are currently wo Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. ``` + ## Jenkins and mr.roboto Plone has a continuous integration (CI) setup and follows CI rules. @@ -112,32 +117,33 @@ Build breakages are a normal and expected part of the development process. Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. Though, there are some essential practices that need to be followed in order to achieve a stable build: -1. Don't check in on a broken build. Check Jenkins first. -2. Always run all commit tests locally before committing. -3. Wait for commit tests to pass before moving on. -4. Never go home on a broken build. -5. Always be prepared to revert to the previous revision. -6. Time-box fixing before reverting. -7. Don't comment out failing tests. -8. Take responsibility for all breakages that result from your changes. +1. Don't check in on a broken build. Check Jenkins first. +2. Always run all commit tests locally before committing. +3. Wait for commit tests to pass before moving on. +4. Never go home on a broken build. +5. Always be prepared to revert to the previous revision. +6. Time-box fixing before reverting. +7. Don't comment out failing tests. +8. Take responsibility for all breakages that result from your changes. See {doc}`continous-integration` for more information. Since it can be burdensome to check this manually, install the tools locally to always see the current state of the Plone CI Server: -- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). -- For macOS there is [CCMenu](http://ccmenu.org/). -- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). -- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). +- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). +- For macOS there is [CCMenu](http://ccmenu.org/). +- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). +- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). These tools were built to parse a specific file that CruiseControl, another CI tool, generated. Jenkins generates this file too. You can configure your notifier of choice with this url: `https://jenkins.plone.org/cc.xml` [which is a 404, LOL!] + ## Check out packages to fix Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. -It can be a little daunting at first to find out which packages cause the bug in question, but just ask in if you need some help. +It can be a little daunting at first to find out which packages cause the bug in question, but just ask in https://community.plone.org/ if you need some help. Once you know which packages you want, pull their source. You can get the source of the package with `mr.developer` and the checkout command, or you can go directly to editing {file}`checkouts.cfg`. @@ -175,6 +181,7 @@ In both methods, `mr.developer` will download the source from GitHub (or otherwi You can repeat this process with as many or as few packages as you need. For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. + ## Testing Locally To run a test for the specific module you modify: @@ -200,6 +207,7 @@ you may just let jenkins do this part for you. More on that below. ``` + ## Updating `CHANGES.rst` and `checkouts.cfg` Once all the tests are running locally on your machine, you are **ALMOST** ready to commit the changes. @@ -224,30 +232,32 @@ Not that you would ever skip running all tests. If your bug is in more than one release, for example 5.2 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg`. + ## Commits and pull requests Review the following checklist: -- Did you fix the original bug? -- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? -- Did you remove any extra code and lingering pdbs? -- Did you write a test case for that bug? -- DO all test cases for the modules and Plone pass? -- Did you update {file}`CHANGES.rst` in each packages you touched? -- Did you add your changed packages to {file}`checkouts.cfg`? +- Did you fix the original bug? +- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? +- Did you remove any extra code and lingering pdbs? +- Did you write a test case for that bug? +- DO all test cases for the modules and Plone pass? +- Did you update {file}`CHANGES.rst` in each packages you touched? +- Did you add your changed packages to {file}`checkouts.cfg`? If you answered *YES* to all of these questions, then you are ready to push your changes! A couple quick reminders: -- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. +- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. Otherwise, please create a `pull request` (more on that below). -- Please try to make one change per commit. +- Please try to make one change per commit. If you are fixing three bugs, make three commits. That way, it is easier to see what was done when, and easier to roll back any changes if necessary. If you want to make large changes cleaning up whitespace or renaming variables, it is especially important to do so in a separate commit for this reason. -- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! +- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! If you commit something REALLY sketchy, they will politely contact you, most likely after immediately reverting changes. - There are no official people assigned to this so if you are especially nervous, ask in . + There are no official people assigned to this so if you are especially nervous, ask in https://community.plone.org/. + ## Commit to `Products.CMFPlone` @@ -309,7 +319,7 @@ git checkout 4.2 git merge my-awesome-feature-4.2 ``` -### Branches and forks and direct commits - oh my +### Branches and forks and direct commits - oh my! ```{note} This section needs a rewrite. @@ -324,10 +334,10 @@ For Plone, this would be the version branch, whereas for most other packages thi HOWEVER, there are a few situations where a branch is appropriate. If you: -- are just getting started -- are not sure about your changes -- want feedback or code review -- are implementing a non-trivial change +- are just getting started +- are not sure about your changes +- want feedback or code review +- are implementing a non-trivial change then you should create a branch of whatever packages you are using, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. Everything about this process would be the same except you need to work on a branch. @@ -359,12 +369,13 @@ This will turn your request into a pull request on the main branch. There are people who look once a week or more for pending pull requests and will confirm whether or not it's a good fix, and give you feedback where necessary. The reviewers are informal and very nice, so don't worry. They are there to help! -If you want immediate feedback, visit with the pull request link and ask for a review. +If you want immediate feedback, visit https://community.plone.org/ with the pull request link and ask for a review. ```{note} You still need to update the file {file}`checkouts.cfg` in the correct branches of `buildout.coredev`! ``` + ## Finalize issues If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. @@ -372,6 +383,7 @@ We don't have integration with GitHub yet so it's a nice way to track changes. It also lets the reporter know that you care. If the bug is really bad, consider pinging the release manager and asking them to make a release. + ## FAQ How do I know when my package got made? diff --git a/coredev/git.md b/coredev/git.md index 992de6aa6d..10696f8d36 100644 --- a/coredev/git.md +++ b/coredev/git.md @@ -17,17 +17,19 @@ All this can go, it's redundant Our repository on GitHub has the following layout: -- **feature branches**: +- **feature branches**: All development for new features must be done in dedicated branches, normally one branch per feature. -- **main** or **master** **branch**: +- **main** or **master** **branch**: when features get completed they are merged into the master branch; bugfixes are commited directly on the master branch, -- **tags**: +- **tags**: whenever we create a new release, we tag the repository so we can later retrace our steps, or rerelease versions. + ## Git basics Some introductory definitions and concepts, if you are already familiar enough with Git, head to next section: {ref}`general-guidelines-label`. + ### Mental working model With Git (as well as all modern [DVCS](http://en.wikipedia.org/wiki/Distributed_revision_control)), distributing changes to others is a two steps process (contrary to traditional VCS like `svn`). @@ -44,6 +46,7 @@ You can freely fix/change/remove/rework/update/... your commits afterwards. Push your changes whenever you are sure they are what you, and others, expect them to be. + ### Concepts In Git there are: diff --git a/coredev/guidelines.md b/coredev/guidelines.md index a931c3eb12..331c25e346 100644 --- a/coredev/guidelines.md +++ b/coredev/guidelines.md @@ -23,34 +23,35 @@ Let's bring you up to speed with the minimum you need to know to start contribut ## Create an issue -- If you know the issue is for a specific package, you can add an issue there. +- If you know the issue is for a specific package, you can add an issue there. When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues). -- Please specify a few things: +- Please specify a few things: - - What steps reproduce the problem? - - What do you expect when you do that? - - What happens instead? - - Which Plone version are you using? + - What steps reproduce the problem? + - What do you expect when you do that? + - What happens instead? + - Which Plone version are you using? -- If it is a visual issue, can you add a screen shot? +- If it is a visual issue, can you add a screen shot? -- If there is an error in the Site Setup error log, please include it. +- If there is an error in the Site Setup error log, please include it. Especially a traceback is helpful. Click on the 'Display traceback as text' link if you see it in the error log. + ## Create a pull request -- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. +- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. This means that we can NOT accept pull requests from you unless this is done, so please don't put the code reviewers at risk and do it anyways. -- Add a changelog entry as file in the news directory. +- Add a changelog entry as file in the news directory. For helpful instructions, please see: -- For new features, an addition to README.rst is probably needed. +- For new features, an addition to README.rst is probably needed. A package may include other documentation that needs updating. -- All text that can be shown in a browser must be translatable. +- All text that can be shown in a browser must be translatable. Please mark all such strings as translatable. -- Be nice and use code quality checkers like flake8 and jshint. -- See if you can use git to squash multiple commits into one where this makes sense. +- Be nice and use code quality checkers like flake8 and jshint. +- See if you can use git to squash multiple commits into one where this makes sense. If you are not comfortable with git, never mind. -- If after reading this you become hesitant: don't worry. +- If after reading this you become hesitant: don't worry. You can always create a pull request, mark it as WIP (work in progress), and improve the above points later. diff --git a/coredev/index.md b/coredev/index.md index 38bf4fc7be..41192a3579 100644 --- a/coredev/index.md +++ b/coredev/index.md @@ -16,6 +16,7 @@ Most of this can go This part describes the process of development in Plone. It is primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). + ## Plone Contributor Agreement You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). @@ -23,6 +24,7 @@ You must sign the [Plone Contributor Agreement](https://plone.org/foundation/con We can **NOT** accept pull requests from you until you have signed and returned the Contributor Agreement, and been approved. Please don't put the code reviewers at risk by ignoring this requirement. + ## Contents ```{toctree} @@ -40,6 +42,7 @@ git package-dependencies ``` + ## Additional material These are some documents used as reference for this documentation. @@ -61,4 +64,4 @@ The style guides are ancient and need to be overhauled. Documenation's style is guided by Vale and the Microsoft Style Guide. See [Contributing to Documentation](https://6.docs.plone.org/contributing/index.html). -Our coding style guides are located at the [Plone Style Guide]( section. +Our coding style guides are located at the [Plone Style Guide](https://5.docs.plone.org/develop/styleguide/index.html section. diff --git a/coredev/mrdeveloper.md b/coredev/mrdeveloper.md index f1a280f210..f0480b0c1b 100644 --- a/coredev/mrdeveloper.md +++ b/coredev/mrdeveloper.md @@ -14,7 +14,7 @@ Review, but keep # `mr.developer` This buildout uses `mr.developer` to manage package development. -See for more information, or run `bin/develop help` for a list of available commands. +See https://pypi.org/project/mr.developer/ for more information, or run `bin/develop help` for a list of available commands. The most common workflow to get all the latest updates is: diff --git a/coredev/packages-dependencies.md b/coredev/packages-dependencies.md index 2f8ba1145f..8f95a4f704 100644 --- a/coredev/packages-dependencies.md +++ b/coredev/packages-dependencies.md @@ -15,20 +15,22 @@ Needs grammar/style check, and re-do the ASCII art as Mermaid diagram for added This chapter describes the architecture of Plone's packages and dependencies. + ## Motivation In the past, lots of indirections were introduced in Plone's packages and dependecies. Our goal in the long run is to untangle them and get a direct dependency graph. This document shows the current state as an orientation. + ## Overview There are multiple level of dependencies: -- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) -- Python level (imports) -- ZCML level (includes) -- testing (need for layers, such as functional testing) +- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) +- Python level (imports) +- ZCML level (includes) +- testing (need for layers, such as functional testing) We do not have any circular dependencies at the package level anymore. This was solved already. @@ -36,6 +38,7 @@ This was solved already. Nevertheless we have indirection on all other levels. Since Plone consists of a lot of packages, it is complex to untangle those. + ## Mental model A base mental model for how Plone is organized in Plone 6 since alpha 4 is shown in the following diagram: @@ -97,8 +100,9 @@ A base mental model for how Plone is organized in Plone 6 since alpha 4 is shown As a rough model we have two packages as dividing lines: -1. `Products.CMFPlone` -2. `plone.base` +1. `Products.CMFPlone` +2. `plone.base` + ## Packages in detail @@ -106,256 +110,263 @@ If we look deeper into those, we have more sub-dividers, but first group all int Then, based on the 6.0.0.a4 release, these are the packages: + ### Above `Products.CMFPlone` -- Plone -- plone.api -- plone.app.iterate -- plone.app.upgrade -- plone.restapi -- plone.volto -- Products.CMFPlacefulWorkflow +- Plone +- plone.api +- plone.app.iterate +- plone.app.upgrade +- plone.restapi +- plone.volto +- Products.CMFPlacefulWorkflow + ### Between `Products.CMFPlone` and `plone.base` -- collective.monkeypatcher -- plone.app.caching -- plone.app.content -- plone.app.contentlisting -- plone.app.contentmenu -- plone.app.contentrules -- plone.app.contenttypes -- plone.app.customerize -- plone.app.dexterity -- plone.app.discussion -- plone.app.event -- plone.app.i18n -- plone.app.intid -- plone.app.layout -- plone.app.linkintegrity -- plone.app.locales -- plone.app.lockingbehavior -- plone.app.multilingual -- plone.app.portlets -- plone.app.querystring -- plone.app.redirector -- plone.app.registry -- plone.app.relationfield -- plone.app.textfield -- plone.app.theming -- plone.app.users -- plone.app.uuid -- plone.app.versioningbehavior -- plone.app.viewletmanager -- plone.app.vocabularies -- plone.app.widgets -- plone.app.workflow -- plone.app.z3cform -- plone.browserlayer -- plone.cachepurging -- plone.contentrules -- plone.formwidget.namedfile -- plone.formwidget.recurrence -- plone.i18n -- plone.namedfile -- plone.outputfilters -- plone.portlet.collection -- plone.portlet.static -- plone.portlets -- plone.protect -- plone.resourceeditor -- plone.rfc822 -- plone.schemaeditor -- plone.session -- plone.staticresources -- plone.stringinterp -- plone.theme -- plonetheme.barceloneta -- Products.isurlinportal +- collective.monkeypatcher +- plone.app.caching +- plone.app.content +- plone.app.contentlisting +- plone.app.contentmenu +- plone.app.contentrules +- plone.app.contenttypes +- plone.app.customerize +- plone.app.dexterity +- plone.app.discussion +- plone.app.event +- plone.app.i18n +- plone.app.intid +- plone.app.layout +- plone.app.linkintegrity +- plone.app.locales +- plone.app.lockingbehavior +- plone.app.multilingual +- plone.app.portlets +- plone.app.querystring +- plone.app.redirector +- plone.app.registry +- plone.app.relationfield +- plone.app.textfield +- plone.app.theming +- plone.app.users +- plone.app.uuid +- plone.app.versioningbehavior +- plone.app.viewletmanager +- plone.app.vocabularies +- plone.app.widgets +- plone.app.workflow +- plone.app.z3cform +- plone.browserlayer +- plone.cachepurging +- plone.contentrules +- plone.formwidget.namedfile +- plone.formwidget.recurrence +- plone.i18n +- plone.namedfile +- plone.outputfilters +- plone.portlet.collection +- plone.portlet.static +- plone.portlets +- plone.protect +- plone.resourceeditor +- plone.rfc822 +- plone.schemaeditor +- plone.session +- plone.staticresources +- plone.stringinterp +- plone.theme +- plonetheme.barceloneta +- Products.isurlinportal + ### The foundation below `plone.base` + #### Plone world -- borg.localrole -- plone.alterego -- plone.autoform -- plone.autoinclude -- plone.batching -- plone.behavior -- plone.caching -- plone.dexterity -- plone.event -- plone.folder -- plone.indexer -- plone.intelligenttext -- plone.keyring -- plone.locking -- plone.memoize -- plone.registry -- plone.resource -- plone.rest -- plone.scale -- plone.schema -- plone.subrequest -- plone.supermodel -- plone.transformchain -- plone.uuid -- plone.z3cform -- Products.DateRecurringIndex -- Products.ExtendedPathIndex -- Products.MimetypesRegistry -- Products.PlonePAS -- Products.PortalTransforms -- Products.statusmessages +- borg.localrole +- plone.alterego +- plone.autoform +- plone.autoinclude +- plone.batching +- plone.behavior +- plone.caching +- plone.dexterity +- plone.event +- plone.folder +- plone.indexer +- plone.intelligenttext +- plone.keyring +- plone.locking +- plone.memoize +- plone.registry +- plone.resource +- plone.rest +- plone.scale +- plone.schema +- plone.subrequest +- plone.supermodel +- plone.transformchain +- plone.uuid +- plone.z3cform +- Products.DateRecurringIndex +- Products.ExtendedPathIndex +- Products.MimetypesRegistry +- Products.PlonePAS +- Products.PortalTransforms +- Products.statusmessages + #### Zope ecosystem -- Chameleon -- diazo -- five.customerize -- five.intid -- five.localsitemanager -- icalendar -- Products.CMFCore -- Products.CMFDiffTool -- Products.CMFDynamicViewFTI -- Products.CMFEditions -- Products.CMFUid -- Products.DCWorkflow -- Products.ExternalMethod -- Products.GenericSetup -- Products.MailHost -- Products.PluggableAuthService -- Products.PluginRegistry -- Products.PythonScripts -- Products.Sessions -- Products.SiteErrorLog -- Products.StandardCacheManagers -- Products.ZopeVersionControl -- repoze.xmliter -- webresource -- z3c.caching -- z3c.form -- z3c.formwidget.query -- z3c.objpath -- z3c.pt -- z3c.relationfield -- z3c.zcmlhook -- zc.recipe.egg -- zc.relation -- zodbverify -- zope.copy -- zope.intid -- zope.keyreference +- Chameleon +- diazo +- five.customerize +- five.intid +- five.localsitemanager +- icalendar +- Products.CMFCore +- Products.CMFDiffTool +- Products.CMFDynamicViewFTI +- Products.CMFEditions +- Products.CMFUid +- Products.DCWorkflow +- Products.ExternalMethod +- Products.GenericSetup +- Products.MailHost +- Products.PluggableAuthService +- Products.PluginRegistry +- Products.PythonScripts +- Products.Sessions +- Products.SiteErrorLog +- Products.StandardCacheManagers +- Products.ZopeVersionControl +- repoze.xmliter +- webresource +- z3c.caching +- z3c.form +- z3c.formwidget.query +- z3c.objpath +- z3c.pt +- z3c.relationfield +- z3c.zcmlhook +- zc.recipe.egg +- zc.relation +- zodbverify +- zope.copy +- zope.intid +- zope.keyreference + #### Zope core -- AccessControl -- Acquisition -- AuthEncoding -- beautifulsoup4 -- BTrees -- DateTime -- DocumentTemplate -- ExtensionClass -- Missing -- MultiMapping -- Persistence -- persistent -- Products.BTreeFolder2 -- Products.ZCatalog -- Record -- RestrictedPython -- transaction -- zc.lockfile -- ZConfig -- zdaemon -- ZEO -- zExceptions -- ZODB -- ZODB3 -- zodbpickle -- Zope -- zope.annotation -- zope.app.locales -- zope.browser -- zope.browsermenu -- zope.browserpage -- zope.browserresource -- zope.cachedescriptors -- zope.component -- zope.componentvocabulary -- zope.configuration -- zope.container -- zope.contentprovider -- zope.contenttype -- zope.datetime -- zope.deferredimport -- zope.deprecation -- zope.dottedname -- zope.event -- zope.exceptions -- zope.filerepresentation -- zope.globalrequest -- zope.hookable -- zope.i18n -- zope.i18nmessageid -- zope.interface -- zope.lifecycleevent -- zope.location -- zope.pagetemplate -- zope.processlifetime -- zope.proxy -- zope.ptresource -- zope.publisher -- zope.ramcache -- zope.schema -- zope.security -- zope.sendmail -- zope.sequencesort -- zope.site -- zope.size -- zope.structuredtext -- zope.tal -- zope.tales -- zope.testbrowser -- zope.testing -- zope.traversing -- zope.viewlet -- Zope2 +- AccessControl +- Acquisition +- AuthEncoding +- beautifulsoup4 +- BTrees +- DateTime +- DocumentTemplate +- ExtensionClass +- Missing +- MultiMapping +- Persistence +- persistent +- Products.BTreeFolder2 +- Products.ZCatalog +- Record +- RestrictedPython +- transaction +- zc.lockfile +- ZConfig +- zdaemon +- ZEO +- zExceptions +- ZODB +- ZODB3 +- zodbpickle +- Zope +- zope.annotation +- zope.app.locales +- zope.browser +- zope.browsermenu +- zope.browserpage +- zope.browserresource +- zope.cachedescriptors +- zope.component +- zope.componentvocabulary +- zope.configuration +- zope.container +- zope.contentprovider +- zope.contenttype +- zope.datetime +- zope.deferredimport +- zope.deprecation +- zope.dottedname +- zope.event +- zope.exceptions +- zope.filerepresentation +- zope.globalrequest +- zope.hookable +- zope.i18n +- zope.i18nmessageid +- zope.interface +- zope.lifecycleevent +- zope.location +- zope.pagetemplate +- zope.processlifetime +- zope.proxy +- zope.ptresource +- zope.publisher +- zope.ramcache +- zope.schema +- zope.security +- zope.sendmail +- zope.sequencesort +- zope.site +- zope.size +- zope.structuredtext +- zope.tal +- zope.tales +- zope.testbrowser +- zope.testing +- zope.traversing +- zope.viewlet +- Zope2 + #### Libraries -- attrs -- cffi -- cssselect -- decorator -- docutils -- feedparser -- future -- importlib_metadata -- jsonschema -- Markdown -- multipart -- Paste -- PasteDeploy -- piexif -- Pillow -- pycparser -- PyJWT -- pyrsistent -- python_dotenv -- python_gettext -- requests -- roman -- sgmllib3k -- simplejson -- soupsieve -- Unidecode -- urllib3 -- waitress -- WebOb -- WebTest -- WSGIProxy2 -- zipp +- attrs +- cffi +- cssselect +- decorator +- docutils +- feedparser +- future +- importlib_metadata +- jsonschema +- Markdown +- multipart +- Paste +- PasteDeploy +- piexif +- Pillow +- pycparser +- PyJWT +- pyrsistent +- python_dotenv +- python_gettext +- requests +- roman +- sgmllib3k +- simplejson +- soupsieve +- Unidecode +- urllib3 +- waitress +- WebOb +- WebTest +- WSGIProxy2 +- zipp diff --git a/coredev/plip-review.md b/coredev/plip-review.md index 074a182faa..267b559022 100644 --- a/coredev/plip-review.md +++ b/coredev/plip-review.md @@ -15,6 +15,7 @@ Combine with PLIP page, remove obsolete technologies, go over language A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. + ## Expectations A good PLIP review takes about four hours. @@ -22,6 +23,7 @@ Please plan accordingly. When you are done, if you have access to core, commit the review to the `plips` folder, and reference the PLIP in your commit message. If you do not have access, attach your review to the PLIP ticket itself. + ## Setting up the environment Follow the instructions in {doc}`getting-started-with-development`. @@ -32,43 +34,48 @@ Instead of running the buildout with the default buildout file, you will run the ./bin/buildout -c plips/plipXXXX.cfg ``` + ## Functionality review This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. + ### General -- Does the PLIP actually do what the implementers proposed? +- Does the PLIP actually do what the implementers proposed? Are there incomplete variations? -- Were there any errors running buildout? +- Were there any errors running buildout? Did the migration(s) work? -- Do error and status messages make sense? +- Do error and status messages make sense? Are they properly internationalized? -- Are there any performance considerations? +- Are there any performance considerations? Has the implementer addressed them, if so? + ### Bugs -- Are there any bugs? +- Are there any bugs? Nothing is too big nor small. -- Do fields handle wacky data? +- Do fields handle wacky data? How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? +- Is validation up to snuff and sensical? Is it too restrictive or not restrictive enough? + ### Usability Issues -- Is the implementation usable? -- How will novice end users respond to the change? -- Does this PLIP need a usability review? +- Is the implementation usable? +- How will novice end users respond to the change? +- Does this PLIP need a usability review? If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. -- Is the PLIP consistent with the rest of Plone? +- Is the PLIP consistent with the rest of Plone? For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? +- Does everything flow nicely for novice and advanced users? Is there any workflow that feels odd? -- Are there any new permissions and do they work properly? +- Are there any new permissions and do they work properly? Does their role assignment make sense? + ### Documentation Issues - Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? @@ -80,20 +87,23 @@ This way the implementer can find help if they need it. Also set a priority for the ticket. The PLIP will not be merged until all blockers and critical bugs are fixed. + ### Code Review + #### Python -- Is this code maintainable? -- Is the code properly documented? -- Does the code adhere to PEP8 standards (more or less)? -- Are they importing deprecated modules? +- Is this code maintainable? +- Is the code properly documented? +- Does the code adhere to PEP8 standards (more or less)? +- Are they importing deprecated modules? + #### JavaScript -- Does the JavaScript meet our set of JavaScript standards? +- Does the JavaScript meet our set of JavaScript standards? See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). -- Does the JavaScript work in all currently supported browsers? +- Does the JavaScript work in all currently supported browsers? Is it performant? ```{todo} @@ -103,7 +113,7 @@ See https://github.com/plone/documentation/issues/1330 #### ME/TAL -- Does the PLIP use views appropriately, avoiding too much logic? -- Is there any code in a loop that could potentially be a performance issue? -- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? +- Does the PLIP use views appropriately, avoiding too much logic? +- Is there any code in a loop that could potentially be a performance issue? +- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? +- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? diff --git a/coredev/plips.md b/coredev/plips.md index 5de254d162..90b071eacb 100644 --- a/coredev/plips.md +++ b/coredev/plips.md @@ -18,10 +18,12 @@ It is a change to a Plone package that would affect everyone. PLIPs go through a different process than bug fixes because of their broad reaching effect. The Plone Framework Team reviews all PLIPs to be sure that it's in the best interest of the broader community to be implemented and that it is of high quality. + ## Frequently asked questions about PLIPs This section provides detailed answers to common questions about PLIPs. + ### PLIP or bugfix? In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. @@ -30,6 +32,7 @@ The Framework Team is eager to reduce its own workload and will reclassify it fo If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. The key point here is that each change must be documented, allowing it to be tracked and understood. + ### Who can submit PLIPs? Anyone who has signed a Plone Contributor Agreement can work on a PLIP. @@ -47,6 +50,7 @@ If you have ideas on new interactions or UI your ideas are more than welcome. We will help you pair up with implementers if needed. + ### What is a PLIP champion? When you submit your PLIP and it is approved, a Framework Team member who is especially excited about seeing the PLIP completed will be assigned to your PLIP as a champion. @@ -55,14 +59,15 @@ They are there to push you through completion, as well as answer any questions a A champion fulfill the following tasks. -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. +- Answer any questions the PLIP implementor has, technical or otherwise. +- Encourage the PLIP author by constantly giving feedback and encouragement. +- Keep the implementer aware of timelines, and push to get things done on time. +- Assist with finding additional help when needed to complete the implementation in a timely matter. Keep in mind that champions are in passive mode by default. If you need help or guidance, please reach out to them as soon as possible to activate help mode. + ### Can I get involved in other ways? If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. @@ -76,6 +81,7 @@ Then, follow the instructions for {doc}`reviewing a PLIP `. Thank you in advance! + ### When can I submit a PLIP? Today, tomorrow, any time! @@ -84,6 +90,7 @@ After the PLIP is accepted, the Framework Team will try to judge complexity and You can begin work immediately, and we encourage submitting fast and furious. + ### When is the PLIP due? **Summary: As soon as you get it done.** @@ -95,27 +102,30 @@ In general, we don't want to track a PLIP for more than a year. If your PLIP is accepted and we haven't seen activity in over a year, we will probably ask you to restart the whole process. + ### What happens if your PLIP is not accepted? If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. It is often the case that there are competing implementations, and we want to see it vetted as an add-on before "blessing" a preferred implementation. + ## Process Overview -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. +1. Submit a PLIP at any time. +2. PLIP is approved for inclusion into core for a given release. +3. Developer implements PLIP (code, tests, documentation). +4. PLIP is submitted for review by developer. +5. Framework Team reviews the PLIP and gives feedback. +6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. +7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. +8. PLIP is approved for merge. In rare circumstances, a PLIP will be rejected. This is usually the result of the developer not responding to feedback or dropping out of the process. Hang in there! -9. After all other PLIPs are merged, a release is cut. +9. After all other PLIPs are merged, a release is cut. Standby for bugs! + (how-to-submit-a-plip)= ## How to submit a PLIP @@ -145,15 +155,16 @@ Others may be able to point out risks or even offer up better or existing soluti Please note a few things: -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. +- It is very rare that the "Risks" section will be empty or none. +- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. +- The seconder field is REQUIRED. We will send the PLIP back to you if it is not filled in. Currently, this is just someone else who thinks your PLIP is a good idea, a +1. In the near future, we will start asking that the seconder is either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. + ### Evaluating PLIPs After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. @@ -166,38 +177,41 @@ Please keep your eyes and inbox open for changes. These are the criteria by which the framework team will review your work: -- What is size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? +- What is size and status of the work needed to be done? +- Is it already an add-on and well established? +- Is this idea well baked and expressed clearly? +- Does the work proposed belong in Plone now, or in the future? +- Is this PLIP more appropriate as a qualified add-on? +- Is this PLIP too risky? See the {doc}`plip-review` page for more information. + ## Implementing your PLIP You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. + ### General Rules -- Any new packages must be in a branch in the `plone` namespace in GitHub. +- Any new packages must be in a branch in the `plone` namespace in GitHub. You don't have to develop there, but it must be there when submitted. We recommend using branches off of the repositories under the Plone GitHub organization, and will detail that below. -- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. -- Any new code must: +- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. +- Any new code must: - - Be {doc}`properly documented `. - - Have clear code. - - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). + - Be {doc}`properly documented `. + - Have clear code. + - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). For convenience and better code quality use Python, JavaScript, and other code linting plugins in your editor. - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). + - [Be tested](https://5.docs.plone.org/develop/testing/index.html). ```{todo} Update links from Plone 5 to Plone 6 Documentation, once content is migrated. See https://github.com/plone/documentation/issues/1330 and other issues. ``` + ### Creating a new PLIP branch Create a buildout configuration file for your PLIP in the `plips` folder. @@ -232,6 +246,7 @@ zcml += Use the same naming convention when you branch existing packages. You should always branch packages when working on PLIPs. + ### Working on a PLIP To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: @@ -258,15 +273,16 @@ installed = .installed.cfg var = ./var ``` + ### Finishing up Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. This file should be called {file}`plip__notes.txt`. This should include, but is not limited to: -- URLs pointing to all documentation created and updated -- Any concerns and issues still remaining -- Any weird buildout things +- URLs pointing to all documentation created and updated +- Any concerns and issues still remaining +- Any weird buildout things Once you have finished, update your PLIP issue to indicate that it is ready for review. The Framework Team will assign 2-3 people to review your PLIP. diff --git a/coredev/release.md b/coredev/release.md index 674bd5b2a1..3d4ff8ac87 100644 --- a/coredev/release.md +++ b/coredev/release.md @@ -15,6 +15,7 @@ Can stay, as it needs a place to live. Check in with Release Managers to update This chapter describes the process to release Plone and its packages. + ## Release process for Plone packages To keep the Plone software stack maintainable, the Python egg release process must be automated to a high degree. @@ -29,20 +30,21 @@ This command includes the following requirements. All files mentioned in this list may be written in Markdown or reStructuredText and have the appropriate file name suffix. ``` -- All releases must be hosted on PyPI. -- All versions must be tagged in version control. -- Each package must have a {file}`README` file with links to the version control repository and issue tracker. -- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. -- {file}`CHANGES` must contain release dates. -- {file}`README` and {file}`CHANGES` must be visible on PyPI. -- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. +- All releases must be hosted on PyPI. +- All versions must be tagged in version control. +- Each package must have a {file}`README` file with links to the version control repository and issue tracker. +- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. +- {file}`CHANGES` must contain release dates. +- {file}`README` and {file}`CHANGES` must be visible on PyPI. +- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. -- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). +- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). ```{seealso} [High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). ``` + ## Special packages The Plone Release Team releases the core Plone packages. @@ -58,13 +60,14 @@ These are: `plone.app.locales` : Please leave this to the i18n team lead, Vincent Fretin. + ## Plone core release process checklist -1. Check Jenkins status. +1. Check Jenkins status. Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org/). It should be green, but if it is not, fix the problem first. -2. Check out `buildout.coredev`. +2. Check out `buildout.coredev`. ```shell git clone git@github.com:plone/buildout.coredev.git @@ -74,45 +77,45 @@ These are: bin/buildout -c buildout.cfg ``` -3. Check packages for updates. +3. Check packages for updates. Check all packages for updates, add to or remove from `checkouts.cfg` accordingly. This script may help: ```shell bin/manage report --interactive ``` - + This step should not be needed, because we do the check for every single commit, but people may still have forgotten to add a package to the `checkouts.cfg` file. -4. Check packages individually. +4. Check packages individually. Use the `bin/fullrelease` script from the core development buildout. This includes extra checks that we have added in `plone.releaser`. It guides you through all the next steps. - 1. Check changelog. + 1. Check changelog. Check if `CHANGES` is up-to-date. All changes since the last release should be included. A "Fixes" or "New" header should be included, with the relevant changes under it. Upgrade notes are best placed here as well. Compare `git log HEAD...` with `CHANGES`, or from `zest.releaser` use the command `lasttaglog `. - 2. Run [pyroma](https://pypi.org/project/pyroma/). - 3. Run [check-manifest](https://pypi.org/project/check-manifest/). - 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). - 5. Check if the version in `setup.py` is correct and follows our versioning best practice. - 6. Make a release (zest.releaser: `bin/fullrelease`) - 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. - -5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. -6. Update CMFPlone version in `profiles/default/metadata.xml`. -7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. -8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). - - 1. Copy all core packages there. - 2. Possibly make an alpha or beta release of CMFPlone. - 3. Copy the `versions.cfg` file from coredev to there. - -9. Write an email to the Plone developers list announcing a pending release. + 2. Run [pyroma](https://pypi.org/project/pyroma/). + 3. Run [check-manifest](https://pypi.org/project/check-manifest/). + 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). + 5. Check if the version in `setup.py` is correct and follows our versioning best practice. + 6. Make a release (zest.releaser: `bin/fullrelease`) + 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. + +5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. +6. Update CMFPlone version in `profiles/default/metadata.xml`. +7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. +8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). + + 1. Copy all core packages there. + 2. Possibly make an alpha or beta release of CMFPlone. + 3. Copy the `versions.cfg` file from coredev to there. + +9. Write an email to the Plone developers list announcing a pending release. 10. Update `plone.app.locales` version. 11. Create a unified changelog. @@ -124,7 +127,7 @@ These are: 13. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). 14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). 15. Create a release page on [plone.org](https://plone.org/download/releases) -16. Send links to the installers list at . +16. Send links to the installers list at plone-installers@lists.sourceforge.net. 17. Wait for installers to be uploaded to Launchpad, with a link to the plone.org release page. 18. Publish release page on plone.org. 19. Update plone.org homepage links to point to the new release. diff --git a/coredev/roboto.md b/coredev/roboto.md index a195e0adec..ef2e7a1091 100644 --- a/coredev/roboto.md +++ b/coredev/roboto.md @@ -21,30 +21,31 @@ Add brief description of what is Mr. Roboto and what it does. When a push happens on GitHub, `mr.roboto` is triggered and it starts to analyze the push. -- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. +- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. In this case, we send to `plone-cvs` the commit to keep track of the commits on that list. -- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. +- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. This kgs job is a snapshot of the last working version of the `buildout.coredev` with the newest version of the package that is involved on the push. These jobs are really fast, as we only test the package applied to the kgs Plone and Python version `coredev` buildout. -- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at . +- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at http://jenkins.plone.org/roboto/plips. ```{todo} `http://jenkins.plone.org/roboto/plips` is obsolete, and returns a 404 not found. ``` + ## Job finishes When Jenkins finishes a job, it makes a callback to `mr.roboto`, which in turn does the following: -- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. +- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. It does this one time only, with all the information, so no more empty mails from the GitHub notification system. -- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. +- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. We also send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. -- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. +- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. For all kgs jobs jenkins sends an email to the author with the results when is finished. -All the notifications have an URL similar to . +All the notifications have an URL similar to http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10. ```{todo} http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 is obsolete, and returns a 404 not found. @@ -52,9 +53,9 @@ http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 i On this URL, there is the commit hash, who committed it, the diff, the files, and the result for each Jenkins job. -- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. -- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. -- The author receives the results of tests failing against kgs after ten minutes after the push. +- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. +- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. +- The author receives the results of tests failing against kgs after ten minutes after the push. ```{note} In case of integration errors with other packages that may fail because of the push, kgs will not be aware of that. diff --git a/coredev/troubleshooting.md b/coredev/troubleshooting.md index 7dcc0f98c2..61a94d3f3d 100644 --- a/coredev/troubleshooting.md +++ b/coredev/troubleshooting.md @@ -15,11 +15,13 @@ Needs review. In general, a 'troubleshooting' page is nice, but this looks outda This chapter describes how to troubleshoot development issues in Plone. + ## Buildout issues Buildout can be frustrating for those unfamiliar with parsing through autistic robot language. These errors are almost always a quick fix, and a little bit of understanding goes a long way. + ### Errors running `bootstrap.py` You may not even get to running buildout, and then you will already have an error. @@ -62,6 +64,7 @@ You may get the same error above again, but now that you know how to fix it, you Hooray! + ### When `mr.developer` is unhappy `mr.developer` is never unhappy, except when it is. @@ -107,6 +110,7 @@ allow-hosts += sphinx.pocoo.org Again, this is only necessary if the package wasn't found in the end. + ### `mr.developer` path errors ```console @@ -121,18 +125,21 @@ To fix, do: ln -s plips/.mr.developer.cfg ``` + ## Other random issues ```{TODO} These need to be revalidated ``` + ### Dirty packages ```console ERROR: Can't update package 'Some package', because it's dirty. ``` + #### Fix `mr.developer` is complaining because a file has been changed or added, but not committed. @@ -140,6 +147,7 @@ ERROR: Can't update package 'Some package', because it's dirty. Use `bin/develop update --force`. Adding `*.pyc *~.nib *.egg-info .installed.cfg *.pt.py *.cpt.py *.zpt.py *.html.py *.egg` to your subversion configuration's `global-ignores` has been suggested as a more permanent solution. + ### No module named zope 2 ```console @@ -149,6 +157,7 @@ ImportError: No module named Zope2" when building using a PLIP cfg file. Appears to not actually be the case. Delete {file}`mkzopeinstance.py` from {file}`bin/`, and rerun buildout to correct this if you're finding it irksome. + ### Can't open file '/Startup/run.py' Two possible fixes. @@ -158,6 +167,7 @@ If you use Python 2.4 by mistake, use 2.6 instead. Or you may need to make sure you run `bin/buildout …` after `bin/develop …`. Try removing {file}`parts/*`, {file}`bin/*`, {file}`.installed.cfg`, then re-bootstrap and re-run buildout, develop, buildout. + ### Missing PIL {file}`pil.cfg` is included within this buildout to aid in PIL installation. @@ -165,6 +175,7 @@ Run {command}`bin/buildout -c pil.cfg` to install. This method does not work on Windows. We're unable to run it by default. + ### Modified egg issues {command}`bin/develop status` is showing that the `Products.CMFActionIcons` egg has been modified, but I haven't touched it. From 6449526e325e2d4da45e27fefe1228b052ebe01a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 19 Jun 2024 00:28:08 -0700 Subject: [PATCH 03/69] Minor grammar fixes, restore whitespace, one line per sentence, emphasis not strong --- .../core/continuous-integration.md | 51 ++++++++++++------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md index ed195183b9..9cf3e6fdaa 100644 --- a/docs/contributing/core/continuous-integration.md +++ b/docs/contributing/core/continuous-integration.md @@ -13,7 +13,8 @@ The {term}`CI` system at [jenkins.plone.org](https://jenkins.plone.org) is a sha Build breakages are a normal and expected part of the development process. The aim is to find errors and remove them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential practices that you need follow to achieve a stable build: +However, there are some essential practices that you need follow to achieve a stable build: + ## 1) Don't check in on a broken build @@ -26,43 +27,52 @@ Checking in further changes and triggering new builds will complicate matters an If the build is broken over a longer period of time (more than a couple of hours) you should either: -- notify the developer who is responsible for the breakage -- fix the problem yourself -- or revert the commit so you and others can continue to work. +- notify the developer who is responsible for the breakage +- fix the problem yourself +- revert the commit so you and others can continue to work ```{note} There is one exception to this rule. Sometimes there are changes or tests that depend on changes in other packages. If this is the case, there is no way around breaking a single build for a certain period of time. -In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. +In this case, run the all tests locally with all the changes and commit them within a time frame of ten minutes. ``` + ## 2) Always run all commit tests locally before committing Follow this practice so the build stays green, and other developers can continue to work without breaking the first rule. -Remember that Plone development can happen all over the world, at all times. So other developers may have checked in changes since your last synchronization. These may interact with your work. +Remember that Plone development can happen all over the world, at all times. +Other developers may have checked in changes since your last synchronization. +These may interact with your work. -Therefore it's essential that you check out ({command}`git pull`) and run the tests again before you push your changes to GitHub. +Therefore it's essential that you merge changes from the main branch into your feature branch, then run the tests again, before you push your changes to GitHub. A common source of errors on check-in is to forget to add some files to the repository. -Use {command}`git status` to check and correct for this. Also double-check to not check in files that should not be part of a package, such as editor configuration files. +Use {command}`git status` to check and correct for this. +Also double-check to not check in files that should not be part of a package, such as editor configuration files and git submodules. + ## 3) Wait for commit tests to pass before moving on Always monitor the build's progress, and fix the problem right away if it fails. -You have a far better chance of fixing the build, if you just introduced a regression than later. +If you introduced a regression, you have a far better chance of fixing the build sooner than later. Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for you. + ## 4) Never go home on a broken build -Take into account the first rule of CI ("Don't check in on a broken build"): breaking the build essentially stops all other developers from working on it. -Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. -It will prevent all other developers to stop working or they will need to fix the errors that you introduced. +Take into account the first rule of CI ("Don't check in on a broken build"). +Breaking the build essentially stops all other developers from working on it. +Therefore going home on a broken build—or even on a build that has not finished yet—is _not_ acceptable. +It will prevent all other developers from working, or they will need to fix the errors that you introduced. + ## 5) Always be prepared to revert to the previous revision -In order for other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. +For other developers to work on the build, you should always be prepared to revert to the previous passing revision. + ## 6) Time-box fixing before reverting @@ -70,28 +80,31 @@ When the build breaks on check-in, try to fix it for ten minutes. If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. This way you will allow other developers to continue to work. + ## 7) Don't comment out failing tests -Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. -While this impulse is understandable, it is **not acceptable**. +Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quickly as possible. +While this impulse is understandable, it is _not acceptable_. The tests were passing for a while and then start to fail. This means that you either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason. You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). + ## 8) Take responsibility for all breakages that result from your changes If you commit a change and all the tests you wrote pass, but others break, the build is still broken. This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. This means that you have introduced a regression bug into the application. -It is **your responsibility** to fix all tests that are not passing because of your changes. +It is _your responsibility_ to fix all tests that do not pass because of your changes. + +There are some tests in Plone that fail randomly, and the community is always working on fixing those. +If you think you hit such a test, try to fix it or re-run the Jenkins job to see if it passes again. -There are some tests in Plone that fail randomly, the community is always working on fixing those. -If you think you hit such a test, try to fix it (better) or re-run the Jenkins job to see if it passes again. +In any case, the developer who made the commit is responsible to make it pass. -In any case the developer who made the commit is responsible to make it pass. ## Further reading From 7d90a292fca07ed54f883b54cd0c8ac250f7d080 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 19 Jun 2024 01:02:04 -0700 Subject: [PATCH 04/69] Revise documentation.md with current resources --- docs/contributing/core/documentation.md | 65 ++++++++++++++++--------- 1 file changed, 43 insertions(+), 22 deletions(-) diff --git a/docs/contributing/core/documentation.md b/docs/contributing/core/documentation.md index 740b868815..70f3b299da 100644 --- a/docs/contributing/core/documentation.md +++ b/docs/contributing/core/documentation.md @@ -15,10 +15,11 @@ For documentation authors, see {doc}`/contributing/documentation/authors`. ## Documentation of Plone -The comprehensive resource for Plone documentation is . +The comprehensive resource for Plone documentation is https://6.docs.plone.org/. The documentation repository is on [GitHub](https://github.com/plone/documentation). Information for how to contribute to documentation can be found at {doc}`/contributing/documentation/index`. + ## Documenting a package At the very least, your package should include the following forms of documentation. @@ -31,51 +32,71 @@ It should be formatted using [GitHub flavored Markdown](https://github.github.co `README.md` should include: -- A brief description of the package's purpose. -- Installation information (How do I get it working?) -- Compatibility information (what versions of Plone does it work with?) -- Links to other sources of documentation. -- Links to issue trackers, mailing lists, and other ways to get help. +- A brief description of the package's purpose +- Installation information +- Version compatibility information +- Links to other sources of documentation +- Links to issue trackers, mailing lists, and other ways to get help + +```{seealso} +{ref}`github-community-health-files-label` +``` + ### The manual (narrative documentation) -The manual goes into further depth for people who want to know all about how to use the package. +The manual should go into further depth for people who want to know all about how to use the package. -It includes topics like: +It should include topics like: -- What are its features -- How to use them (in English — not doctests!) -- Information about architecture -- Common gotchas +- What are its features +- How to use them (in English—not doctests!) +- Information about architecture +- Common gotchas -The manual should consider various audiences who may need different types of information: +The manual should address various audiences who may need different types of information: -- End users who use Plone for content editing, but don't manage the site. -- Site administrators who install and configure the package. -- Integrators who need to extend the functionality of the package in code. -- System administrators who need to maintain the server running the software. +- End users who use Plone for content editing, but don't manage the site. +- Site administrators who install and configure the package. +- Integrators who need to extend the functionality of the package in code. +- System administrators who need to maintain the server running the software. Simple packages with limited functionality can get by with a single page of narrative documentation. In this case, it's simplest to include it in an extended `README.md`. -Some excellent examples of a single-page README are and . +Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching. If your project is moderately complex, you may want to set up your documentation with multiple pages. -The preferred way to do this is to add Sphinx to your project, and host your docs on [readthedocs.org](https://readthedocs.org), so that it rebuilds the documentation whenever you push to GitHub. +The preferred way to do this is to add Sphinx to your project, and host your docs on [readthedocs.org](https://about.readthedocs.com/), so that it rebuilds the documentation whenever you push to GitHub. If you do this, your `README.md` must link off site to the documentation. + ### Reference or API documentation An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code). It is meant for random access to remind the reader of how a particular class or method works, rather than for reading in its entirety. -If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx. +If the code base is written with docstrings, API documentation can be automatically generated using Sphinx. + ### Changes or history -Best practice is to set up [towncrier](https://pypi.org/project/towncrier/) so your package will have a clear and structured history of changes. +```{seealso} +- {ref}`contributing-change-log-label` +- Volto's [`towncrier.toml`](https://github.com/plone/volto/blob/main/packages/volto/towncrier.toml) as an example towncrier configuration file. +``` + ### Licenses -Information about the open source license used for the package should be placed within the `docs` directory. +Information about the open source license used for the package should be placed where GitHub can pick it up and display it as one of its [community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). +The preferred location is at the root of the repository. For Plone core packages, this includes `LICENSE.md` and {file}`LICENSE.GPL`. + + +(github-community-health-files-label)= + +### GitHub community health files + +If your Plone core package lacks a specific community health file, then GitHub will pick up the one configured in the Plone GitHub organization repository [`.github`](https://github.com/plone/.github). +You can override the default files by placing your health file as described in the documentation of [GitHub community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). From e2fb4f8bf4e3509e01b642b96a6bbc6b32d6a8ff Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 20 Jun 2024 03:44:22 -0700 Subject: [PATCH 05/69] - Set the stage for the purpose of this contributing how to guide. It's not an explanation or reference. - Purge git and GitHub material, and refer to first-time contributors. - Modify pre-requisites --- docs/contributing/core/index.md | 286 +++++++++++++++++--------------- 1 file changed, 156 insertions(+), 130 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 6c505c50ad..de83cbb980 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -1,236 +1,262 @@ --- myst: html_meta: - "description": "Contributing to Plone 6 Core" - "property=og:description": "Contributing to Plone 6 Core" - "property=og:title": "Contributing to Plone 6 Core" - "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct" + "description": "Contribute to Plone 6 Core" + "property=og:description": "Contribute to Plone 6 Core" + "property=og:title": "Contribute to Plone 6 Core" + "keywords": "Plone, Plone Contributor Agreement, License" --- -# Contributing to Plone 6 core +# Contribute to Plone 6 core -This part describes the process of development in Plone core. -It's primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). +This guide describes the process of how to contribute to, and develop in, Plone core. +It expands upon {doc}`/contributing/index`. + +This guide assumes that you have basic knowledge of how to use git and GitHub. +If you have never contributed to Plone, or you lack basic knowledge of how to use git and GitHub, you should first read {doc}`/contributing/first-time` for more information. + +```{important} +You must {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before your contribution can be accepted. +``` -It expands upon {doc}`/contributing/index` and, where applicable, {doc}`/contributing/first-time`. ## Version support policy -If you are fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule) +Before you contribute to Plone core, check the [version support policy](https://plone.org/download/release-schedule) to see which versions of Plone are currently supported. -## Dependencies + +## Pre-requisites + +It is beyond the scope of this documentation to provide installation instructions for all pre-requisites for your operating system. +However, the following links and sections below may be helpful. ```{include} ../../volto/contributing/install-operating-system.md ``` -- {ref}`setup-build-installation-python-label` {SUPPORTED_PYTHON_VERSIONS} -- {ref}`setup-build-installation-gnu-make-label` -- [git](https://help.github.com/articles/set-up-git/) -- [Pillow](https://pypi.org/project/Pillow/). -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. -- [GCC](https://gcc.gnu.org/) to compile {term}`ZODB`, {term}`Zope` and {term}`lxml`. +- Python {SUPPORTED_PYTHON_VERSIONS} +- {term}`GNU make` +- {term}`Git` +- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers +- [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) to compile {term}`ZODB`, {term}`Zope`, and {term}`lxml` + + +### Python + +Installing Python is beyond the scope of this documentation. +However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. +Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. + + +### Make + +```{include} ../../volto/contributing/install-make.md +``` + -The first step in fixing a bug is getting this [buildout](https://github.com/plone/buildout.coredev) running. -Start with fixing the bug on the latest branch and then [backporting](https://en.wikipedia.org/wiki/Backporting) as necessary. -[GitHub](https://github.com/plone/buildout.coredev/) by default always points to the currently active branch. -Depending on the current development cycle there may exist a future branch. +### Git -At the moment 6.0 is the actively maintained stable branch and 6.1 is the future, currently unstable, active development branch. -More information on switching release branches is below. +```{include} ../../volto/contributing/install-git.md +``` + +### libxml2, libxslt, and GCC + +Consult the resources at the links above for installation instructions. +Package managers may facilitate installation. + + +## Install Plone core for development + +To set up a Plone 6 development environment, change your working directory to wherever you place your projects, and clone https://github.com/plone/buildout.coredev. + +```shell +cd [MY_PROJECTS] +git clone https://github.com/plone/buildout.coredev +cd buildout.coredev +``` -To set up a plone 6 development environment: +Now run the script to install Plone 6. ```shell -cd ~/buildouts # or wherever you want to put things -git clone -b 6.1 https://github.com/plone/buildout.coredev ./plone6devel -cd ./plone6devel ./bootstrap.sh ``` -If you run into issues in this process, please see {doc}`troubleshooting`. +If you run into issues in this process, see {doc}`troubleshooting`. -This will run for a long time if it's your first pull (approximately 20 minutes). -Once that's done pulling down eggs, you can start your new instance with: +This will run for a long time if it's your first pull (approximately 10-20 minutes, depending on network speed and your hardware). + +Once that's done, you can start an instance of Plone with the following command. ```shell ./bin/instance fg ``` -or as {term}`WSGI` service with:: +Alternatively, you can start Plone as a {term}`WSGI` service with the following command. ```shell ./bin/wsgi ``` -To login, the defaults are: +To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser. + +Click {guilabel}`View your Plone site` to do exactly that. -- username: admin -- password: admin +To login, the default credentials are the following. -## Switching branches +- username: `admin` +- password: `admin` -If the bug is specific to one branch or should be [backported](http://en.wikipedia.org/wiki/Backporting), -you can easily switch branches. The first time you get a branch, you must do: + +## Use the correct branch + +```{important} +This section applies to members of the GitHub `plone/developers` team, who have write access to repositories under the Plone GitHub organization. + +Members of the `plone/contributors` team do not have write access, and instead must follow the process to set up their remote upstream and origin branches as described in {ref}`set-up-your-environment-label`. +``` + +The current default and development branch of `buildout.coredev` is `6.1`. +Older versions are named according to their `major.minor` version. + +Always begin by checking out the git branch on which you want to work, usually called `origin`. +If you have not yet checked out a branch, then you need to track it with the `-t` option and specify the remote branch to track. +The following command will switch and track changes from the remote branch `origin/6.1`. ```shell git checkout -t origin/6.1 ``` -This should set up a local 6.1 branch tracking the one on GitHub. -From then on you can do: +If you check out a different branch, and want to return to the previous branch, you need to specify only the local branch. ```shell git checkout 6.1 ``` -To see what branch you are currently on, +Next pull down and merge any recent changes from the remote tracked repository with a single command. ```shell -git branch +git pull ``` -The line with a * by it will indicate which branch you are currently working on. - ```{important} -Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. +Make sure to rerun buildout for the current branch to get the correct versions of packages, otherwise you will get some weird behavior. ``` -## Jenkins and mr.roboto +Next create a new branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. +It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. -Plone has a continuous integration ({term}`CI`) setup and follows CI rules. +```shell +git switch -c 123-my-branch-name -t origin/6.1 +``` -When you push a change to any Plone package, the testing/CI package [mr.roboto](https://github.com/plone/mr.roboto) starts running all the tests to make sure that you don't break anything. -For each Plone and Python version it runs two jobs, one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are affected by your change). +Now you can edit your code without affecting the original branch. -See {doc}`continuous-integration` for more information. -## Check out packages to fix +## Edit packages -Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. -It can be a little daunting at first to find out which packages cause the bug in question, you can ask in if you need some help. -Once you know which packages you want, pull their source. +First identify the names of the Plone packages you want to work on. +If you do not know, you can ask in the [Plone Community Forum](https://community.plone.org/). +Only a few packages are in {file}`src/` by default. -At the base of your buildout, open {file}`checkouts.cfg` and add your package if it's not already there: +Edit the file {file}`checkouts.cfg` at the root of the repository by adding the package names under the `auto-checkout` list. -```cfg +```{code-block} cfg +:emphasize-lines: 10- +[buildout] +always-checkout = force +# always-checkout = false auto-checkout = - # my modified packages - plone.app.caching - plone.caching - # others - ... +# These packages are always checked out: + docs + # +# These packages are manually added, or automatically added by mr.roboto: + # + plone.app.event + icalendar ``` -Then rerun buildout to get the source packages: +Then rerun buildout to install the source packages to edit. ```shell ./bin/buildout ``` -For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. +```{seealso} +For tips on working with `mr.developer`, see {doc}`mrdeveloper`. +``` -## Testing locally -To run a test for the specific module you modify: +## Test locally + +If you change the expected behavior of a feature in a package, you should write a test to cover the change. + +To run a test for the specific package that you modified, use the `-m` option followed by the package name, as shown in the following example. ```shell ./bin/test -m plone.app.caching ``` -These should all run without error. -Please don't check in anything that doesn't succeed! -Now write a test case for the bug you are fixing, and make sure everything is running as it should. +If any test fails, do not commit and push the changes. +Instead write a test that passes. -After the module level tests run with your change, please make sure other modules aren't affected by the change by running the full suite, including robot-tests (remove the `--all` to run without robot tests): +After the package level tests pass with your change, you can run the full unit test suite to ensure other packages aren't affected by the change. +It takes 5-10 minutes to run the full unit test suite. ```shell -./bin/test --all +# Run unit tests +./bin/test ``` -```{note} -Tests take a long time to run. -Once you have enough experience in doing bugfixes, -you may let jenkins do this part for you. -More on that below. -``` - -## Updating `CHANGES.rst` and `checkouts.cfg` +If you run acceptance tests with the `--all` option, it will repeatedly launch and close browser windows that gain focus, disrupting you from doing any other work. +This takes 30-40 minutes to run. +If you can't afford this disruption, you can defer it to Jenkins. -Once all the tests run locally on your machine, you are **ALMOST** ready to commit the changes. -You must perform a couple housekeeping chores before moving on. +```shell +# Run acceptance tests +./bin/test --all +``` -You need to create a change note of what has been modified. -This change note will be collated for the next Plone release and is important for integrators and developers to be able to see what they will get if they upgrade. -Most packages are using [towncrier](https://pypi.org/project/towncrier/). -If that is the case, there will be a directory "news" in the package. Please follow the Towncrier format and put a note in that directory. +## Change log -For packages that haven't switched to using Towncrier, edit {file}`CHANGES.rst` (or {file}`CHANGES.txt`, or {file}`HISTORY.txt`) in each package you have modified and add a summary of the change. New changelog entries should be added at the top of {file}`CHANGES.rst`. +All changes require a change log entry. -Most importantly, if you didn't do it earlier, edit the file {file}`checkouts.cfg` in the buildout directory, and add your changes package to the `auto-checkout` list. -This lets the release manager know that the package has been updated, so that when the next release of Plone is cut, a new egg will be released, and Plone will need to pin to the next version of that package. -In other words, this is how your fix becomes an egg! +For packages that use [towncrier](https://pypi.org/project/towncrier/) to produce change logs, see {ref}`contributing-change-log-label`. -Note that there is a section separator called "# Test Fixes Only". -Make sure your egg is above that line, else your egg probably won't get made quickly. -This tells the release manager that any eggs below this line have tests that are updated, but no code changes. +For packages that don't use towncrier, edit either {file}`CHANGES.rst`, {file}`CHANGES.txt`, or {file}`HISTORY.txt` in each package you have modified, adding a summary of the change. +New change log entries should be added at the top of {file}`CHANGES.rst`. -Modifying the file {file}`checkouts.cfg` also triggers the buildbot, [jenkins](https://jenkins.plone.org/), to pull in the egg and run all the tests against the changes you just made. -If your bug fix is in more than one release, for example 6.1 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg` in both branches. +## Update `checkouts.cfg` -## Commits and pull requests +If you didn't do so earlier, edit the file {file}`checkouts.cfg` at the root, and add your changed packages only to the `auto-checkout` list. +Remove any packages that you previously added to this file, but did not change. +Leave any pre-existing packages in the original list. -Review the following checklist: +The Plone release manager will check this file to see which packages you have updated to make a proper release. -- Did you fix the original bug? -- Is your code consistently formatted? You can use the [Plone Meta](https://github.com/plone/meta) project to set up your development environment to be consistent with Plone community agreed best practices. -- Did you remove any extra code and lingering {term}`pdb` statements? -- Did you write a test case for that bug? -- DO all test cases for the modules and Plone pass? -- Did you write an update note (using Towncrier or via {file}`CHANGES.rst`) in each package you changed? -- Did you add your changed packages to {file}`checkouts.cfg`? +```{seealso} +{doc}`release` +``` -If you answered *Yes* to all, then you are ready to push your changes! -A couple of quick reminders: -- Never commit directly to the development branch. Create a `pull request` (more on that below). -- Please try to make one change per commit. - If you are fixing three bugs, make three commits. - That way, it's easier to see what was done when, and easier to roll back any changes if necessary. - If you want to make large changes cleaning up whitespace or renaming variables, it's especially important to do so in a separate commit for this reason. +## Create a pull request -## Branching and pull requests +After you have completed all the foregoing steps, push your changes to a remote branch and create a pull request in GitHub. -You should create a branch of whatever packages you are updating, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. +If you are working from an issue, return to the original issue, and add a link to the pull request. -Take the `plone.app.caching` example. -After checking it out with `mr.developer`, create your own branch with: -```shell -cd src/plone.app.caching -git checkout -b my_descriptive_branch_name -``` +## Jenkins and mr.roboto -When you are ready to push your fix, push to a remote branch with: +Plone has a continuous integration ({term}`CI`) setup and follows CI rules. -```shell -git push origin my_descriptive_branch_name -``` +When you push a change to a Plone package, there may be GitHub workflows that run automatically. +The CI package [mr.roboto](https://github.com/plone/mr.roboto) will perform some checks and suggest that you run Jenkins after all other CI runs. -This will make a remote branch in GitHub. -Navigate to this branch in the GitHub user interface, and on the top right, there will be a button that says {guilabel}`Pull Request`. -This will turn your request into a pull request on the main branch. -There are people who look once a week or more for pending pull requests and will confirm whether it's a good fix, and give you feedback where necessary. -The reviewers are informal and nice, so don't worry. -They are there to help! -If you want immediate feedback, visit with the pull request link and ask for a review. +For each Plone and Python version, Jenkins runs two jobs: one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are affected by your change). -## Finalize issues +See {doc}`continuous-integration` for more information. -If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. -There is no automatic integration with GitHub yet so it's a nice way to track changes. -It also lets the reporter know that you care. ## Additional material From e719f682ed49853c2947d9e401caa6f628f273ca Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 20 Jun 2024 03:55:34 -0700 Subject: [PATCH 06/69] Pull in RTD PR review config --- .github/workflows/rtd-pr-preview.yml | 22 ++++++++++++++++++++++ .readthedocs.yaml | 25 +++++++++++++++++++++++++ Makefile | 13 ++++++------- 3 files changed, 53 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/rtd-pr-preview.yml create mode 100644 .readthedocs.yaml diff --git a/.github/workflows/rtd-pr-preview.yml b/.github/workflows/rtd-pr-preview.yml new file mode 100644 index 0000000000..bf7bd5aef9 --- /dev/null +++ b/.github/workflows/rtd-pr-preview.yml @@ -0,0 +1,22 @@ +# .github/workflows/rtd-pr-preview.yml +name: readthedocs/actions +on: + pull_request_target: + types: + - opened + # Execute this action only on PRs that touch + # documentation files. + # paths: + # - "docs/**" + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "plone6" + single-version: "true" diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..8beeb58c45 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,25 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + commands: + # Cancel building pull requests when there aren't changes in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; + then + exit 183; + fi + - make rtd-pr-preview diff --git a/Makefile b/Makefile index ac8d6062a1..98e33474b1 100644 --- a/Makefile +++ b/Makefile @@ -224,18 +224,17 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in --port 8050 \ -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) -.PHONY: netlify -netlify: +.PHONY: rtd-pr-preview +rtd-pr-preview: ## Build pull request preview on Read the Docs pip install -r requirements-initial.txt pip install -r requirements.txt - pip install -r requirements-netlify.txt - git submodule init; \ - git submodule update; \ - pip install -e submodules/plone.api[test]; \ + git submodule init + git submodule update + pip install -e submodules/plone.api[test] ln -s ../submodules/volto/docs/source ./docs/volto ln -s ../submodules/plone.restapi ./docs/plone.restapi ln -s ../submodules/plone.api/docs ./docs/plone.api - cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html && cp ./netlify_robots.txt $(BUILDDIR)/html/robots.txt + cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ .PHONY: storybook storybook: From 13871426e82eb8846be72f9a80037d47c5ddc0a4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 20 Jun 2024 04:00:26 -0700 Subject: [PATCH 07/69] Use correct primary branch --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 8beeb58c45..9ae0eeee5e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,7 +18,7 @@ build: # If there are no changes (git diff exits with 0) we force the command to return with 183. # This is a special exit code on Read the Docs that will cancel the build immediately. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/6.0 -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; then exit 183; fi From 51241440ed3150695beed85e61c3334b7789ed82 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 21 Jun 2024 03:11:44 -0700 Subject: [PATCH 08/69] bin/wsgi no workie --- docs/contributing/core/index.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index de83cbb980..31740b408b 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -90,12 +90,6 @@ Once that's done, you can start an instance of Plone with the following command. ./bin/instance fg ``` -Alternatively, you can start Plone as a {term}`WSGI` service with the following command. - -```shell -./bin/wsgi -``` - To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser. Click {guilabel}`View your Plone site` to do exactly that. From ef84d0544d9dda5cf1fddce43832941a01984da1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 21 Jun 2024 03:21:39 -0700 Subject: [PATCH 09/69] Update commit message --- docs/contributing/core/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 31740b408b..cbf2c339ca 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -139,7 +139,7 @@ Next create a new branch on which you want to work from the current branch, trac It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. ```shell -git switch -c 123-my-branch-name -t origin/6.1 +git switch -c 123-thing-i-fixed -t origin/6.1 ``` Now you can edit your code without affecting the original branch. From b3f234761f12b845a70e92f2ce37b3451fb8ab7a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 21 Jun 2024 04:30:02 -0700 Subject: [PATCH 10/69] Update mrdeveloper.md --- docs/contributing/core/mrdeveloper.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/contributing/core/mrdeveloper.md b/docs/contributing/core/mrdeveloper.md index ce14a624dd..db4b0aabf7 100644 --- a/docs/contributing/core/mrdeveloper.md +++ b/docs/contributing/core/mrdeveloper.md @@ -4,30 +4,30 @@ myst: "description": "mr.developer" "property=og:description": "mr.developer" "property=og:title": "mr.developer" - "keywords": "mr.developer" + "keywords": "Plone, buildout, mr.developer" --- # `mr.developer` -This buildout uses `mr.developer` to manage package development. -See [mr.developer on pypi](https://pypi.org/project/mr.developer/) for more information, or run `bin/develop help` for a list of available commands. +Plone core uses `mr.developer` to manage package development. +See [`mr.developer` on PyPI](https://pypi.org/project/mr.developer/) for more information, or run `bin/develop help` for a list of available commands. -The most common workflow to get all the latest updates is: +To get all the latest updates, use the following commands. ```shell git pull bin/develop rebuild ``` -This will get you the latest `coredev` configuration, checkout and update all packages via git in src, and run buildout to configure the whole thing. +This will get you the latest `coredev` configuration, check out and update all packages via git in {file}`src`, and run buildout to configure the whole thing. -From time to time you can check if some old cruft has accumulated: +From time to time you can check if some old cruft has accumulated. ```shell bin/develop status ``` -If this prints any lines with a question mark in front, you can cleanup by: +If this prints any lines with a question mark in front, you can clean the cruft with the following command. ```shell bin/develop purge From 6f92024bd3c0cd683ce9cf03aa8cceee5d137d43 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 21 Jun 2024 04:41:52 -0700 Subject: [PATCH 11/69] Update package-dependencies.md, reverting whitespace changes --- .../contributing/core/package-dependencies.md | 508 +++++++++--------- 1 file changed, 259 insertions(+), 249 deletions(-) diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md index d2270a3955..de5c10c23c 100644 --- a/docs/contributing/core/package-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -11,30 +11,32 @@ myst: This chapter describes the architecture of Plone's packages and dependencies. + ## Motivation -Plone has over the years developed many indirections in its packages and dependencies. +Over the years, Plone has developed many indirections in its packages and dependencies. The goal in the long run is to untangle them and get a simple dependency graph. -This document shows the current state, as orientation. +This document shows the current state, as an orientation to its architecture. + ## Overview There are multiple level of dependencies: -- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) -- Python level (imports) -- ZCML level (includes) -- testing (need for layers, such as functional testing) +- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) +- Python level (imports) +- ZCML level (includes) +- testing (need for layers, such as functional testing) -At some point there were circular dependencies at the package level. -This was solved. +Circular dependencies at the package level have now been resolved. Nevertheless there is indirection on all other levels. Since Plone consists of a lot of packages, it is complex to untangle those. + ## Mental model -A base mental model for how Plone is organized in Plone 6 is shown in the following diagram: +A base mental model for how Plone is organized in Plone 6, and is shown in the following diagram: ```{mermaid} block-beta @@ -45,11 +47,11 @@ block-beta Distributions block:dist plone.volto - plone.classic + plone.classicui end space block:core - coreaddons["Core addons"] + coreaddons["Core add-ons"] coreapi["Core APIs"] end space @@ -86,265 +88,273 @@ space ``` -As a rough model there are two packages as dividing lines: +As a rough model, there are two packages as dividing lines: + +1. `Products.CMFPlone` +2. `plone.base` -1. `Products.CMFPlone` -2. `plone.base` ## Packages in detail -Looking deeper into those, there are more sub-dividers, but first group all into the three groups: +Looking deeper into those packages, there are more sub-divisions, but first we place them into three groups: + ### Above `Products.CMFPlone` -- Plone -- plone.api -- plone.app.iterate -- plone.app.upgrade -- plone.restapi -- plone.volto -- Products.CMFPlacefulWorkflow +- Plone +- plone.api +- plone.app.iterate +- plone.app.upgrade +- plone.restapi +- plone.volto +- Products.CMFPlacefulWorkflow + ### Between `Products.CMFPlone` and `plone.base` -- collective.monkeypatcher -- plone.app.caching -- plone.app.content -- plone.app.contentlisting -- plone.app.contentmenu -- plone.app.contentrules -- plone.app.contenttypes -- plone.app.customerize -- plone.app.dexterity -- plone.app.discussion -- plone.app.event -- plone.app.i18n -- plone.app.intid -- plone.app.layout -- plone.app.linkintegrity -- plone.app.locales -- plone.app.lockingbehavior -- plone.app.multilingual -- plone.app.portlets -- plone.app.querystring -- plone.app.redirector -- plone.app.registry -- plone.app.relationfield -- plone.app.textfield -- plone.app.theming -- plone.app.users -- plone.app.uuid -- plone.app.versioningbehavior -- plone.app.viewletmanager -- plone.app.vocabularies -- plone.app.widgets -- plone.app.workflow -- plone.app.z3cform -- plone.browserlayer -- plone.cachepurging -- plone.contentrules -- plone.formwidget.namedfile -- plone.formwidget.recurrence -- plone.i18n -- plone.namedfile -- plone.outputfilters -- plone.portlet.collection -- plone.portlet.static -- plone.portlets -- plone.protect -- plone.resourceeditor -- plone.rfc822 -- plone.schemaeditor -- plone.session -- plone.staticresources -- plone.stringinterp -- plone.theme -- plonetheme.barceloneta -- Products.isurlinportal +- collective.monkeypatcher +- plone.app.caching +- plone.app.content +- plone.app.contentlisting +- plone.app.contentmenu +- plone.app.contentrules +- plone.app.contenttypes +- plone.app.customerize +- plone.app.dexterity +- plone.app.discussion +- plone.app.event +- plone.app.i18n +- plone.app.intid +- plone.app.layout +- plone.app.linkintegrity +- plone.app.locales +- plone.app.lockingbehavior +- plone.app.multilingual +- plone.app.portlets +- plone.app.querystring +- plone.app.redirector +- plone.app.registry +- plone.app.relationfield +- plone.app.textfield +- plone.app.theming +- plone.app.users +- plone.app.uuid +- plone.app.versioningbehavior +- plone.app.viewletmanager +- plone.app.vocabularies +- plone.app.widgets +- plone.app.workflow +- plone.app.z3cform +- plone.browserlayer +- plone.cachepurging +- plone.contentrules +- plone.formwidget.namedfile +- plone.formwidget.recurrence +- plone.i18n +- plone.namedfile +- plone.outputfilters +- plone.portlet.collection +- plone.portlet.static +- plone.portlets +- plone.protect +- plone.resourceeditor +- plone.rfc822 +- plone.schemaeditor +- plone.session +- plone.staticresources +- plone.stringinterp +- plone.theme +- plonetheme.barceloneta +- Products.isurlinportal + ### The foundation below `plone.base` + #### Plone world -- borg.localrole -- plone.alterego -- plone.autoform -- plone.autoinclude -- plone.batching -- plone.behavior -- plone.caching -- plone.dexterity -- plone.event -- plone.folder -- plone.indexer -- plone.intelligenttext -- plone.keyring -- plone.locking -- plone.memoize -- plone.registry -- plone.resource -- plone.rest -- plone.scale -- plone.schema -- plone.subrequest -- plone.supermodel -- plone.transformchain -- plone.uuid -- plone.z3cform -- Products.DateRecurringIndex -- Products.ExtendedPathIndex -- Products.MimetypesRegistry -- Products.PlonePAS -- Products.PortalTransforms -- Products.statusmessages +- borg.localrole +- plone.alterego +- plone.autoform +- plone.autoinclude +- plone.batching +- plone.behavior +- plone.caching +- plone.dexterity +- plone.event +- plone.folder +- plone.indexer +- plone.intelligenttext +- plone.keyring +- plone.locking +- plone.memoize +- plone.registry +- plone.resource +- plone.rest +- plone.scale +- plone.schema +- plone.subrequest +- plone.supermodel +- plone.transformchain +- plone.uuid +- plone.z3cform +- Products.DateRecurringIndex +- Products.ExtendedPathIndex +- Products.MimetypesRegistry +- Products.PlonePAS +- Products.PortalTransforms +- Products.statusmessages + #### Zope ecosystem -- Chameleon -- diazo -- five.customerize -- five.intid -- five.localsitemanager -- icalendar -- Products.CMFCore -- Products.CMFDiffTool -- Products.CMFDynamicViewFTI -- Products.CMFEditions -- Products.CMFUid -- Products.DCWorkflow -- Products.ExternalMethod -- Products.GenericSetup -- Products.MailHost -- Products.PluggableAuthService -- Products.PluginRegistry -- Products.PythonScripts -- Products.Sessions -- Products.SiteErrorLog -- Products.StandardCacheManagers -- Products.ZopeVersionControl -- repoze.xmliter -- webresource -- z3c.caching -- z3c.form -- z3c.formwidget.query -- z3c.objpath -- z3c.pt -- z3c.relationfield -- z3c.zcmlhook -- zc.recipe.egg -- zc.relation -- zodbverify -- zope.copy -- zope.intid -- zope.keyreference +- Chameleon +- diazo +- five.customerize +- five.intid +- five.localsitemanager +- icalendar +- Products.CMFCore +- Products.CMFDiffTool +- Products.CMFDynamicViewFTI +- Products.CMFEditions +- Products.CMFUid +- Products.DCWorkflow +- Products.ExternalMethod +- Products.GenericSetup +- Products.MailHost +- Products.PluggableAuthService +- Products.PluginRegistry +- Products.PythonScripts +- Products.Sessions +- Products.SiteErrorLog +- Products.StandardCacheManagers +- Products.ZopeVersionControl +- repoze.xmliter +- webresource +- z3c.caching +- z3c.form +- z3c.formwidget.query +- z3c.objpath +- z3c.pt +- z3c.relationfield +- z3c.zcmlhook +- zc.recipe.egg +- zc.relation +- zodbverify +- zope.copy +- zope.intid +- zope.keyreference + #### Zope core -- AccessControl -- Acquisition -- AuthEncoding -- beautifulsoup4 -- BTrees -- DateTime -- DocumentTemplate -- ExtensionClass -- Missing -- MultiMapping -- Persistence -- persistent -- Products.BTreeFolder2 -- Products.ZCatalog -- Record -- RestrictedPython -- transaction -- zc.lockfile -- ZConfig -- zdaemon -- ZEO -- zExceptions -- ZODB -- ZODB3 -- zodbpickle -- Zope -- zope.annotation -- zope.app.locales -- zope.browser -- zope.browsermenu -- zope.browserpage -- zope.browserresource -- zope.cachedescriptors -- zope.component -- zope.componentvocabulary -- zope.configuration -- zope.container -- zope.contentprovider -- zope.contenttype -- zope.datetime -- zope.deferredimport -- zope.deprecation -- zope.dottedname -- zope.event -- zope.exceptions -- zope.filerepresentation -- zope.globalrequest -- zope.hookable -- zope.i18n -- zope.i18nmessageid -- zope.interface -- zope.lifecycleevent -- zope.location -- zope.pagetemplate -- zope.processlifetime -- zope.proxy -- zope.ptresource -- zope.publisher -- zope.ramcache -- zope.schema -- zope.security -- zope.sendmail -- zope.sequencesort -- zope.site -- zope.size -- zope.structuredtext -- zope.tal -- zope.tales -- zope.testbrowser -- zope.testing -- zope.traversing -- zope.viewlet -- Zope2 +- AccessControl +- Acquisition +- AuthEncoding +- beautifulsoup4 +- BTrees +- DateTime +- DocumentTemplate +- ExtensionClass +- Missing +- MultiMapping +- Persistence +- persistent +- Products.BTreeFolder2 +- Products.ZCatalog +- Record +- RestrictedPython +- transaction +- zc.lockfile +- ZConfig +- zdaemon +- ZEO +- zExceptions +- ZODB +- ZODB3 +- zodbpickle +- Zope +- zope.annotation +- zope.app.locales +- zope.browser +- zope.browsermenu +- zope.browserpage +- zope.browserresource +- zope.cachedescriptors +- zope.component +- zope.componentvocabulary +- zope.configuration +- zope.container +- zope.contentprovider +- zope.contenttype +- zope.datetime +- zope.deferredimport +- zope.deprecation +- zope.dottedname +- zope.event +- zope.exceptions +- zope.filerepresentation +- zope.globalrequest +- zope.hookable +- zope.i18n +- zope.i18nmessageid +- zope.interface +- zope.lifecycleevent +- zope.location +- zope.pagetemplate +- zope.processlifetime +- zope.proxy +- zope.ptresource +- zope.publisher +- zope.ramcache +- zope.schema +- zope.security +- zope.sendmail +- zope.sequencesort +- zope.site +- zope.size +- zope.structuredtext +- zope.tal +- zope.tales +- zope.testbrowser +- zope.testing +- zope.traversing +- zope.viewlet +- Zope2 + #### Libraries -- attrs -- cffi -- cssselect -- decorator -- docutils -- feedparser -- future -- importlib_metadata -- jsonschema -- Markdown -- multipart -- Paste -- PasteDeploy -- piexif -- Pillow -- pycparser -- PyJWT -- pyrsistent -- python_dotenv -- python_gettext -- requests -- roman -- sgmllib3k -- simplejson -- soupsieve -- Unidecode -- urllib3 -- waitress -- WebOb -- WebTest -- WSGIProxy2 -- zipp +- attrs +- cffi +- cssselect +- decorator +- docutils +- feedparser +- future +- importlib_metadata +- jsonschema +- Markdown +- multipart +- Paste +- PasteDeploy +- piexif +- Pillow +- pycparser +- PyJWT +- pyrsistent +- python_dotenv +- python_gettext +- requests +- roman +- sgmllib3k +- simplejson +- soupsieve +- Unidecode +- urllib3 +- waitress +- WebOb +- WebTest +- WSGIProxy2 +- zipp From 57cd6fdd4d302ec4f1dbc579d983d7c303847c3a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 21 Jun 2024 04:49:49 -0700 Subject: [PATCH 12/69] Revert whitespace changes, restore TODO --- docs/contributing/core/plip-review.md | 65 ++++++++++++++++----------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md index 670838c932..aa979067dd 100644 --- a/docs/contributing/core/plip-review.md +++ b/docs/contributing/core/plip-review.md @@ -11,14 +11,16 @@ myst: A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. + ## Expectations A good PLIP review takes about four hours. Please plan accordingly. -When you are done, if you have access to core, commit the review to the `plips` folder of [buildout.coredev](https://github.com/plone/buildout.coredev), and reference the PLIP in your commit message. +When you are done, if you have access to core, commit the review to the `plips` folder of [`buildout.coredev`](https://github.com/plone/buildout.coredev), and reference the PLIP in your commit message. If you do not have access, attach your review to the PLIP ticket itself. + ## Setting up the environment Follow the instructions in {doc}`index`. @@ -29,44 +31,48 @@ Instead of running the buildout with the default buildout file, you will run the ./bin/buildout -c plips/plip-XXXX.cfg ``` + ## Functionality review This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. + ### General -- Does the PLIP actually do what the implementers proposed? +- Does the PLIP actually do what the implementers proposed? Are there incomplete variations? -- Were there any errors running buildout? +- Were there any errors running buildout? Did the migration(s) work? -- Do error and status messages make sense? +- Do error and status messages make sense? Are they properly internationalized? -- Are there any performance considerations? +- Are there any performance considerations? Has the implementer addressed them, if so? -- For changes in the UI, are they accessible for people using assisted technologies? + ### Bugs -- Are there any bugs? +- Are there any bugs? Nothing is too big nor small. -- Do fields handle wacky, incomplete or harmful data? +- Do fields handle wacky data? How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? +- Is validation up to snuff and sensical? Is it too restrictive or not restrictive enough? + ### Usability Issues -- Is the implementation usable? -- How will novice end users respond to the change? -- Does this PLIP need a usability review? +- Is the implementation usable? +- How will novice end users respond to the change? +- Does this PLIP need a usability review? If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. -- Is the PLIP consistent with the rest of Plone? +- Is the PLIP consistent with the rest of Plone? For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? +- Does everything flow nicely for novice and advanced users? Is there any workflow that feels odd? -- Are there any new permissions and do they work properly? +- Are there any new permissions and do they work properly? Does their role assignment make sense? + ### Documentation Issues - Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? @@ -78,24 +84,33 @@ This way the implementer can find help if they need it. Also set a priority for the ticket. The PLIP will not be merged until all blockers and critical bugs are fixed. + ### Code Review + #### Python -- Is this code maintainable? -- Is the code properly documented? -- Does the code adhere to Plone best practices for formatting? -- Are they importing deprecated modules? +- Is this code maintainable? +- Is the code properly documented? +- Does the code adhere to PEP8 standards (more or less)? +- Are they importing deprecated modules? + #### JavaScript -- Does the JavaScript meet Plone's set of JavaScript standards? -- Does the JavaScript work in all currently supported browsers? +- Does the JavaScript meet our set of JavaScript standards? + See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). +- Does the JavaScript work in all currently supported browsers? Is it performant? +```{todo} +Update links from Plone 5 Documentation to Plone 6 Documentation, when they exist. +See https://github.com/plone/documentation/issues/1330 +``` + #### ME/TAL -- Does the PLIP use views appropriately, avoiding too much logic? -- Is there any code in a loop that could potentially be a performance issue? -- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? +- Does the PLIP use views appropriately, avoiding too much logic? +- Is there any code in a loop that could potentially be a performance issue? +- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? +- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? From e626b6569505c14e0a86e1d4ad819530031e7d61 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 21 Jun 2024 05:07:38 -0700 Subject: [PATCH 13/69] Revert whitespace muckery --- docs/contributing/core/plips.md | 58 ++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 7f7b766d9f..ed8e9e859a 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -15,10 +15,12 @@ It is a change to a Plone package that would affect everyone. PLIPs go through a different process than bug fixes because of their broad reach. The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. + ## Frequently asked questions about PLIPs This section provides detailed answers to common questions about PLIPs. + ### PLIP or bugfix? In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. @@ -27,6 +29,7 @@ The Framework Team will reclassify it if your proposal falls below the threshold If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. The key point here is that each change must be documented, allowing it to be tracked and understood. + ### Who can submit PLIPs? Anyone who has signed a Plone Contributor Agreement can work on a PLIP. @@ -51,10 +54,10 @@ They are there to help you through completion, answer questions and provide guid A champion fulfills the following tasks: -- Answer any questions the PLIP implementer has, technical or otherwise. -- Encourage the PLIP author by giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. +- Answer any questions the PLIP implementor has, technical or otherwise. +- Encourage the PLIP author by constantly giving feedback and encouragement. +- Keep the implementer aware of timelines, and push to get things done on time. +- Assist with finding additional help when needed to complete the implementation in a timely matter. Keep in mind that champions are volunteers as well, and have other tasks in life. That means you will have to play an active role in asking for help or guidance. @@ -72,12 +75,14 @@ Then, follow the instructions for {doc}`reviewing a PLIP `. Thank you in advance! + ### When can I submit a PLIP? Today, tomorrow, any time! After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. + ### When is the PLIP due? **Summary: As soon as you get it done.** @@ -87,27 +92,30 @@ Sometimes life gets in the way, and a PLIP may have to be re-assigned to the fol In general, PLIPs shouldn't take more than a year, otherwise they should be closed. A new PLIP can follow up if there is more capacity to see it through. + ### What happens if your PLIP is not accepted? If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. It is often the case that there are competing implementations, and the community wants to see it vetted as an add-on before "blessing" a particular implementation. + ## Process Overview -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. +1. Submit a PLIP at any time. +2. PLIP is approved for inclusion into core for a given release. +3. Developer implements PLIP (code, tests, documentation). +4. PLIP is submitted for review by developer. +5. Framework Team reviews the PLIP and gives feedback. +6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. +7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. +8. PLIP is approved for merge. In rare circumstances, a PLIP will be rejected. This is usually the result of the developer not responding to feedback or dropping out of the process. Hang in there! -9. After all other PLIPs are merged, a release is cut. +9. After all other PLIPs are merged, a release is cut. Standby for bugs! + (how-to-submit-a-plip)= ## How to submit a PLIP @@ -137,15 +145,16 @@ Others may be able to point out risks or even offer up better or existing soluti Please note a few things: -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. +- It is very rare that the "Risks" section will be empty or none. +- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. +- The seconder field is REQUIRED. The PLIP will be sent back to you if it is not filled in. Currently, this is just someone else who thinks your PLIP is a good idea, a +1. In the near future, the seconder should either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. + ### Evaluating PLIPs After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. @@ -158,19 +167,21 @@ Please keep your eyes and inbox open for changes. These are the criteria by which the framework team will review your work: -- What is the size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? +- What is size and status of the work needed to be done? +- Is it already an add-on and well established? +- Is this idea well baked and expressed clearly? +- Does the work proposed belong in Plone now, or in the future? +- Is this PLIP more appropriate as a qualified add-on? +- Is this PLIP too risky? See the {doc}`plip-review` page for more information. + ## Implementing your PLIP You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. + ### General Rules - Any new packages must be in a branch in the `plone` namespace in GitHub. @@ -189,6 +200,7 @@ Update links from Plone 5 to Plone 6 Documentation, once content is migrated. See https://github.com/plone/documentation/issues/1330 and other issues. ``` + ### Creating a new PLIP branch Create a buildout configuration file for your PLIP in the `plips` folder of {file}`buildout.coredev`. @@ -224,6 +236,7 @@ zcml += Use the same naming convention when you branch existing packages. You should always branch packages when working on PLIPs. + ### Working on a PLIP To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: @@ -250,6 +263,7 @@ installed = .installed.cfg var = ./var ``` + ### Finishing up Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. From a79fe1fb975f7576029961ce07bcbc9e3100594d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 22 Jun 2024 05:30:02 -0700 Subject: [PATCH 14/69] Revise and make recommendations in plips.md to remove coaching and focus on how to do things. --- docs/contributing/core/plips.md | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index ed8e9e859a..7272c8994f 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -9,9 +9,7 @@ myst: # Plone Improvement Proposals (PLIPs) -A {term}`PLIP` is a Plone Improvement Proposal. - -It is a change to a Plone package that would affect everyone. +A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone. PLIPs go through a different process than bug fixes because of their broad reach. The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. @@ -34,23 +32,25 @@ The key point here is that each change must be documented, allowing it to be tra Anyone who has signed a Plone Contributor Agreement can work on a PLIP. -You do not have to be the most amazing coder in the world to submit a PLIP. +```{todo} +The FWT no longer participates in PLIPs. +Recommend deletion of next two paragraphs. +``` The Framework Team is happy to help you at any point in the process. -Submitting a PLIP can be a great learning process. - When the PLIP is accepted, a Framework Team member will "champion" your PLIP and follow up to its completion. -PLIPs are not just for code experts. -If you have ideas on new interactions or UI your ideas are more than welcome. - -The community will help you pair up with implementers if needed. ### What is a PLIP champion? +```{todo} +This section is no longer in practice. +Recommend deletion. +``` + When you submit your PLIP and it is approved, a Framework Team member will take on the role of champion for that PLIP. -They are there to help you through completion, answer questions and provide guidance. +They are there to help you through completion, answer questions, and provide guidance. A champion fulfills the following tasks: @@ -62,19 +62,15 @@ A champion fulfills the following tasks: Keep in mind that champions are volunteers as well, and have other tasks in life. That means you will have to play an active role in asking for help or guidance. + ### Can I get involved in other ways? If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. -Ask one of the Framework Team members what PLIPs are available for review, or check the status of PLIPs at the [GitHub issues](https://github.com/plone/Products.CMFPlone/issues) page -for [Products.CMFPlone](https://github.com/Plone/Products.CMFPlone) -for [issues tagged with "03 type: feature (plip)"](https://github.com/plone/Products.CMFPlone/labels/03%20type%3A%20feature%20%28plip%29). -Make sure to let the community know you intend to review the PLIP by communicating that to the [Framework Team](https://community.plone.org/c/development/framework-team). +Check the status of PLIPs at https://github.com/search?q=path%3A%2Fplone+label%3A%2203+type%3A+feature+%28plip%29%22++&type=issues&ref=advsearch&state=open. Then, follow the instructions for {doc}`reviewing a PLIP `. -Thank you in advance! - ### When can I submit a PLIP? From ea65b7ce484e727b1b7acad40b1f903023519279 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 22 Jun 2024 16:46:39 -0700 Subject: [PATCH 15/69] Move FAQ to the end to elevate the process overview. Revise process overview without the FWT, as it appears to be an ex-FWT, or possibly just pining for the fjords. --- docs/contributing/core/plips.md | 201 ++++++++++++++++---------------- 1 file changed, 101 insertions(+), 100 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 7272c8994f..6b880840da 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -9,117 +9,35 @@ myst: # Plone Improvement Proposals (PLIPs) -A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone. -PLIPs go through a different process than bug fixes because of their broad reach. +A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone who uses that package. +PLIPs go through a formal process compared to bug fixes because of their broad reach. The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. -## Frequently asked questions about PLIPs - -This section provides detailed answers to common questions about PLIPs. +## Process overview +1. Developer submits a PLIP. +2. [Some indeterminate team?] approves the PLIP for inclusion into Plone core for a given release. +3. Developer implements the PLIP, including code, tests, and documentation. +4. Developer creates a pull request of the PLIP for review by the team. +5. [Some indeterminate team?] reviews the PLIP and gives feedback. +6. Developer addresses concerns from the feedback, and resubmits the PLIP, if necessary. +7. Repeat the two previous steps, until both the [Some indeterminate team?] and developer are happy with the result. +8. [Somebody] approves the PLIP for merge. +9. [Somebody] merges the PLIP. -### PLIP or bugfix? +In rare circumstances, a PLIP may be rejected. +This is usually the result of the developer not responding to feedback or dropping out of the process. -In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. -When in doubt, submit it as a PLIP. -The Framework Team will reclassify it if your proposal falls below the threshold. -If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. -The key point here is that each change must be documented, allowing it to be tracked and understood. - - -### Who can submit PLIPs? - -Anyone who has signed a Plone Contributor Agreement can work on a PLIP. - -```{todo} -The FWT no longer participates in PLIPs. -Recommend deletion of next two paragraphs. -``` -The Framework Team is happy to help you at any point in the process. - -When the PLIP is accepted, a Framework Team member will "champion" your PLIP and follow up to its completion. +(submit-a-plip)= -### What is a PLIP champion? - -```{todo} -This section is no longer in practice. -Recommend deletion. -``` - -When you submit your PLIP and it is approved, a Framework Team member will take on the role of champion for that PLIP. - -They are there to help you through completion, answer questions, and provide guidance. - -A champion fulfills the following tasks: - -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. - -Keep in mind that champions are volunteers as well, and have other tasks in life. -That means you will have to play an active role in asking for help or guidance. - - -### Can I get involved in other ways? - -If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. - -Check the status of PLIPs at https://github.com/search?q=path%3A%2Fplone+label%3A%2203+type%3A+feature+%28plip%29%22++&type=issues&ref=advsearch&state=open. - -Then, follow the instructions for {doc}`reviewing a PLIP `. - - -### When can I submit a PLIP? - -Today, tomorrow, any time! - -After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. - - -### When is the PLIP due? - -**Summary: As soon as you get it done.** - -Ideally, a PLIP should be completed for the release to which it's assigned. -Sometimes life gets in the way, and a PLIP may have to be re-assigned to the following release. - -In general, PLIPs shouldn't take more than a year, otherwise they should be closed. A new PLIP can follow up if there is more capacity to see it through. - - -### What happens if your PLIP is not accepted? - -If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. -It is often the case that there are competing implementations, and the community wants to see it vetted as an add-on before "blessing" a particular implementation. - - -## Process Overview - -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. - In rare circumstances, a PLIP will be rejected. - This is usually the result of the developer not responding to feedback or dropping out of the process. - Hang in there! -9. After all other PLIPs are merged, a release is cut. - Standby for bugs! - - -(how-to-submit-a-plip)= - -## How to submit a PLIP +## Submit a PLIP Whether you want to update the default theme, or rip out a piece of architecture, major changes should go through the PLIP process. -If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team). +If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team/12). -A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues/new) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. +A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. To get started, open a new issue. The issue will be prefilled with headings and comments for a bug or a PLIP. @@ -284,3 +202,86 @@ During the merge phase you must be prepared to help out with all the features an If all went as planned, the next Plone release will carry on with your PLIP in it. You'll be expected to help out with that feature after it's been released (within reason). + + +## Frequently asked questions about PLIPs + +This section provides detailed answers to common questions about PLIPs. + + +### PLIP or bug fix? + +In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. +When in doubt, submit it as a PLIP. +The Framework Team will reclassify it if your proposal falls below the threshold. +If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. +The key point here is that each change must be documented, allowing it to be tracked and understood. + + +### Who can submit PLIPs? + +Anyone who has signed a Plone Contributor Agreement can work on a PLIP. + +```{todo} +The FWT no longer participates in PLIPs. +Recommend deletion of next two paragraphs. +``` +The Framework Team is happy to help you at any point in the process. + +When the PLIP is accepted, a Framework Team member will "champion" your PLIP and follow up to its completion. + + +### What is a PLIP champion? + +```{todo} +This section is no longer in practice. +Recommend deletion. +``` + +When you submit your PLIP and it is approved, a Framework Team member will take on the role of champion for that PLIP. + +They are there to help you through completion, answer questions, and provide guidance. + +A champion fulfills the following tasks: + +- Answer any questions the PLIP implementor has, technical or otherwise. +- Encourage the PLIP author by constantly giving feedback and encouragement. +- Keep the implementer aware of timelines, and push to get things done on time. +- Assist with finding additional help when needed to complete the implementation in a timely matter. + +Keep in mind that champions are volunteers as well, and have other tasks in life. +That means you will have to play an active role in asking for help or guidance. + + +### Can I get involved in other ways? + +If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. + +Check the status of PLIPs at https://github.com/search?q=path%3A%2Fplone+label%3A%2203+type%3A+feature+%28plip%29%22++&type=issues&ref=advsearch&state=open. + +Then, follow the instructions for {doc}`reviewing a PLIP `. + + +### When can I submit a PLIP? + +Today, tomorrow, any time! + +After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. + + +### When is the PLIP due? + +**Summary: As soon as you get it done.** + +Ideally, a PLIP should be completed for the release to which it's assigned. +Sometimes life gets in the way, and a PLIP may have to be re-assigned to the following release. + +In general, PLIPs shouldn't take more than a year, otherwise they should be closed. A new PLIP can follow up if there is more capacity to see it through. + + +### What happens if your PLIP is not accepted? + +If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. +It is often the case that there are competing implementations, and the community wants to see it vetted as an add-on before "blessing" a particular implementation. + + From d1b54fc1dd9b3c9c290d1fa41d6646588e9d6916 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 22 Jun 2024 16:46:49 -0700 Subject: [PATCH 16/69] Fix linkcheck redirect --- docs/contributing/core/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index f9eba0c43b..76d5d52971 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -121,7 +121,7 @@ These are: 14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). 15. Create a release page on [plone.org](https://plone.org/download/releases) 16. Wait for installers to be uploaded to Launchpad, with a link to the [plone.org](https://plone.org/download/releases) release page. -17. Publish release page on [plone.org](https://plone.org). +17. Publish release page on [plone.org](https://plone.org/). 18. Update plone.org homepage links to point to the new release. 19. Send out announcement to the plone-announce email distribution list. 20. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. From aa5a028f8fef927023d294f7ad34828153610be8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 23 Jun 2024 03:35:15 -0700 Subject: [PATCH 17/69] Revise how to submit a PLIP for today --- docs/contributing/core/plips.md | 120 ++++++++++++++------------------ 1 file changed, 52 insertions(+), 68 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 6b880840da..ef1a5cce3f 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -9,6 +9,13 @@ myst: # Plone Improvement Proposals (PLIPs) +```{todo} +This page needs extensive review. +It is not clear whether the Framework Team still exists, and PLIPs are now spread over many repositories. + +See https://community.plone.org/t/plips-documentation/19609 +``` + A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone who uses that package. PLIPs go through a formal process compared to bug fixes because of their broad reach. The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. @@ -17,14 +24,14 @@ The Plone Framework Team reviews all PLIPs to make sure that it's in the best in ## Process overview 1. Developer submits a PLIP. -2. [Some indeterminate team?] approves the PLIP for inclusion into Plone core for a given release. +2. [SOME_INDETERMINATE_TEAM] approves the PLIP for inclusion into Plone core for a given release. 3. Developer implements the PLIP, including code, tests, and documentation. -4. Developer creates a pull request of the PLIP for review by the team. -5. [Some indeterminate team?] reviews the PLIP and gives feedback. +4. Developer creates a pull request of the PLIP for review by the [SOME_INDETERMINATE_TEAM]. +5. [SOME_INDETERMINATE_TEAM] reviews the PLIP and gives feedback. 6. Developer addresses concerns from the feedback, and resubmits the PLIP, if necessary. -7. Repeat the two previous steps, until both the [Some indeterminate team?] and developer are happy with the result. -8. [Somebody] approves the PLIP for merge. -9. [Somebody] merges the PLIP. +7. Repeat the two previous steps, until both the [SOME_INDETERMINATE_TEAM] and developer are happy with the result. +8. [SOMEBODY] approves the PLIP for merge. +9. [SOMEBODY] merges the PLIP. In rare circumstances, a PLIP may be rejected. This is usually the result of the developer not responding to feedback or dropping out of the process. @@ -34,88 +41,65 @@ This is usually the result of the developer not responding to feedback or droppi ## Submit a PLIP -Whether you want to update the default theme, or rip out a piece of architecture, major changes should go through the PLIP process. -If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team/12). - -A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. - -To get started, open a new issue. -The issue will be prefilled with headings and comments for a bug or a PLIP. -Remove the bug part. -Fill in all applicable fields. -After submitting, select the tag `03 type: feature (plip)` for the issues. - -When writing a PLIP, be as specific and to-the-point as you can. -Remember your audience. -To get support for your proposal, people will have to be able to read it! +Prepare the following information for your PLIP. -A good PLIP is sufficiently clear for a knowledgeable Plone user to understand the proposed changes, and sufficiently detailed for the release manager and other developers to understand the full impact the proposal would have on the code base. +- Title +- Proposer (you) +- Seconder (another person supporting your PLIP) +- Abstract (a comprehensive overview of the subject) +- Motivation (reason or motivation for creating this proposal) +- Assumptions (preconditions) +- Proposal & Implementation (detailed proposal with implementation details and–if needed—possible variants to be discussed) +- Deliverables (packages and documentation chapters involved, including any third party packages) +- Risks (what will break or affect existing installations of Plone after an upgrade, including the end user point of view, training efforts, and other audiences) +- Participants (list of persons and roles known) -You don't have to list every line of code that needs to be changed, but you should also give an indication that you have some idea of how the change can be feasibly implemented. +Now that you are prepared, submit your PLIP. -After your PLIP is written, solicit feedback on your idea on the [Plone Community Forum](https://community.plone.org/). -In this vetting process, you want to make sure that the change won't adversely affect other people on accident. -Others may be able to point out risks or even offer up better or existing solutions. +1. Visit the package's GitHub issue tracker, and Click {guilabel}`New issue`. -Please note a few things: + If you do not see the option to create a PLIP, then the repository has not been configured with the PLIP GitHub issue template, and you should instead visit the default Plone issue tracker for PLIPs, [`Products.CMFPlone`](https://github.com/plone/Products.CMFPlone/issues). -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. +2. For the PLIP option, click {guilabel}`Get started`. -The PLIP will be sent back to you if it is not filled in. -Currently, this is just someone else who thinks your PLIP is a good idea, a +1. +3. Fill in the title and description. + Preserve the headings and comments. + The comments provide guidance for you to follow while composing your PLIP. -In the near future, the seconder should either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. +4. When done, click {guilabel}`Submit new issue` to submit your PLIP. + +5. If it does not automatically assign the label {guilabel}`03 type: feature (plip)`, then assign that label to the issue to make it easier to find. -### Evaluating PLIPs +## Get feedback -After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. -If the PLIP is not accepted, please don't be discouraged! +After you submit your PLIP, solicit feedback for your idea on the [Plone Community Forum](https://community.plone.org/). -Most PLIPs first start as an add-on, if possible, to make sure it works in practice. +You may revise your PLIP based on feedback. -All communication with you occurs on the PLIP issue itself. -Please keep your eyes and inbox open for changes. +If you need help at any point in this process, please contact a member of the [SOME_INDETERMINATE_TEAM] personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team/12). -These are the criteria by which the framework team will review your work: -- What is size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? +## Implement your PLIP -See the {doc}`plip-review` page for more information. +You can start the development at any time, but if you intend to modify Plone core, it is a good idea to wait to see if your idea is approved. -## Implementing your PLIP +### General rules -You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. - - -### General Rules - -- Any new packages must be in a branch in the `plone` namespace in GitHub. - You don't have to develop there, but it must be there when submitted. - Use branches off of the repositories under the Plone GitHub organization, see below. -- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. -- Any new code must: - - - Be {doc}`properly documented `. - - Have clear code. - - Follow current best practices in coding style. The [Plone Meta](https://github.com/plone/meta) project can help you set up your environment. For Volto, follow [this guide](https://6.docs.plone.org/volto/contributing/linting.html). - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). For Volto, follow [this guide](https://6.docs.plone.org/volto/contributing/testing.html) - -```{todo} -Update links from Plone 5 to Plone 6 Documentation, once content is migrated. -See https://github.com/plone/documentation/issues/1330 and other issues. -``` +- Any new packages must be in a branch in the `plone` namespace in GitHub. +- The PLIP reviewers must be able run buildout, and everything should "just work"™. +- New code must: + - Be {doc}`properly documented `. If it ain't documented, it's broken. + - Have clear code. + - Follow current best practices in coding style. + The [Plone Meta](https://github.com/plone/meta) project can help you set up your environment. + For Volto, follow {doc}`/volto/contributing/linting`. + - [Be tested](https://5.docs.plone.org/develop/testing/index.html). + For Volto, follow {doc}`/volto/contributing/testing`. -### Creating a new PLIP branch +### Create a new PLIP branch Create a buildout configuration file for your PLIP in the `plips` folder of {file}`buildout.coredev`. From 21453a6ea6c528bbe8bb0799d688d5dc2a5d1809 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 23 Jun 2024 04:09:36 -0700 Subject: [PATCH 18/69] Fix redirect --- docs/contributing/core/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index 76d5d52971..707e4eca95 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -122,6 +122,6 @@ These are: 15. Create a release page on [plone.org](https://plone.org/download/releases) 16. Wait for installers to be uploaded to Launchpad, with a link to the [plone.org](https://plone.org/download/releases) release page. 17. Publish release page on [plone.org](https://plone.org/). -18. Update plone.org homepage links to point to the new release. +18. Update [plone.org](https://plone.org/) homepage links to point to the new release. 19. Send out announcement to the plone-announce email distribution list. 20. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. From ef40380271ffed73f2f45f052203193add919fdf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 02:22:46 -0700 Subject: [PATCH 19/69] Update pre-requisites of libx* and C compiler --- docs/contributing/core/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index cbf2c339ca..5cb6fd7912 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -36,8 +36,7 @@ However, the following links and sections below may be helpful. - Python {SUPPORTED_PYTHON_VERSIONS} - {term}`GNU make` - {term}`Git` -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers -- [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) to compile {term}`ZODB`, {term}`Zope`, and {term}`lxml` +- A C compiler ### Python @@ -58,10 +57,13 @@ Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. ```{include} ../../volto/contributing/install-git.md ``` -### libxml2, libxslt, and GCC +### C compiler -Consult the resources at the links above for installation instructions. -Package managers may facilitate installation. +You need a C compiler on your system to compile {term}`ZODB` and {term}`Zope`. + +On macOS, Developer Tools providers clang for a C compiler. + +On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common option. ## Install Plone core for development From cbb149e610f953e3f468ca2a2f844ff51b853fc0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 02:43:28 -0700 Subject: [PATCH 20/69] Add admonition for non-3.11 Pythons --- docs/contributing/core/index.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 5cb6fd7912..6f45d1a413 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -76,6 +76,20 @@ git clone https://github.com/plone/buildout.coredev cd buildout.coredev ``` +````{important} +If you want to use a Python version that is not 3.11, follow these instructions. + +Open the file {file}`bootstrap.sh` at the root of the repository. +Notice that the script expects Python 3.11 to be installed on your system and in your user's `PATH`. + +```shell +#/bin/sh +`which python3.11` -m venv . +``` + +Edit it according to the Python version you want to use, then save and close the file. +```` + Now run the script to install Plone 6. ```shell From 962a4b981213b3b674a6876e19e8d2d9127b01ac Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 02:56:58 -0700 Subject: [PATCH 21/69] Revise and make recommendations in plips.md to remove coaching and focus on how to do things. --- docs/contributing/core/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 6f45d1a413..d1a7081592 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -108,7 +108,12 @@ Once that's done, you can start an instance of Plone with the following command. To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser. -Click {guilabel}`View your Plone site` to do exactly that. +You will be presented with several options. +Click the button {guilabel}`Create a new Plone site`. + +Enter values in the form, and click the button {guilabel}`Create Plone Site`. + +You will be redirected to your new Plone site. To login, the default credentials are the following. From edee66e4fdb4df1fe47956ea57b8691db2a17887 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 03:37:01 -0700 Subject: [PATCH 22/69] Back off from attempt to use buildout for Volto, and refer to official docs. --- docs/contributing/core/index.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index d1a7081592..bf7e714e2c 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -12,6 +12,11 @@ myst: This guide describes the process of how to contribute to, and develop in, Plone core. It expands upon {doc}`/contributing/index`. +```{important} +Although Plone core includes Volto—the React based, default frontend for Plone 6—this guide does not apply to Volto and its packages. +To contribute to Volto, see {doc}`../volto`. +``` + This guide assumes that you have basic knowledge of how to use git and GitHub. If you have never contributed to Plone, or you lack basic knowledge of how to use git and GitHub, you should first read {doc}`/contributing/first-time` for more information. @@ -109,11 +114,19 @@ Once that's done, you can start an instance of Plone with the following command. To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser. You will be presented with several options. -Click the button {guilabel}`Create a new Plone site`. +Click the button {guilabel}`Create Classic UI Plone site`. Enter values in the form, and click the button {guilabel}`Create Plone Site`. -You will be redirected to your new Plone site. +You will be redirected to your new Classic UI Plone site. + +```{warning} +Ignore the warning about accessing the Plone backend through its Classic UI frontend. + +Do not follow the instructions to install Volto. +They will not work with buildout. +To contribute to Volto, you will need to start over, and follow {doc}`../volto`. +``` To login, the default credentials are the following. From 7e45ba71e13dd06dddcb0afd355cb28f397ce50d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 03:43:39 -0700 Subject: [PATCH 23/69] Use correct git terms, instead of gitterish --- docs/contributing/core/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index bf7e714e2c..b3d6c855ba 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -145,9 +145,9 @@ Members of the `plone/contributors` team do not have write access, and instead m The current default and development branch of `buildout.coredev` is `6.1`. Older versions are named according to their `major.minor` version. -Always begin by checking out the git branch on which you want to work, usually called `origin`. -If you have not yet checked out a branch, then you need to track it with the `-t` option and specify the remote branch to track. -The following command will switch and track changes from the remote branch `origin/6.1`. +Always begin by checking out the git branch on which you want to work. +If you have not yet checked out a branch, then you need to track it with the `-t` option and specify the remote to track, usually called `origin`. +The following command will switch and track changes from the remote `origin` and its branch `6.1`. ```shell git checkout -t origin/6.1 From 0897e15754a63afbc4266af801b0c56203f60ef5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:10:54 -0700 Subject: [PATCH 24/69] Give better instructions not to switch between Plone or coredev.buildout branches --- docs/contributing/core/index.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index b3d6c855ba..d8bbfc85e7 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -71,13 +71,25 @@ On macOS, Developer Tools providers clang for a C compiler. On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common option. + ## Install Plone core for development +The tool that installs Plone core is `buildout.coredev`. + +The current default and development branch of `buildout.coredev` is `6.1` +Older versions are named according to their `major.minor` version. +Its versions align with Plone's `major.minor` versions. + +Use a separate directory for each version of Plone to which you want to contribute. +This will avoid switching between git branches, then re-running buildout, which can cause dependency conflicts between versions of Plone. + To set up a Plone 6 development environment, change your working directory to wherever you place your projects, and clone https://github.com/plone/buildout.coredev. +You can specify the branch that you want to check out with the `-b` option. ```shell cd [MY_PROJECTS] -git clone https://github.com/plone/buildout.coredev +# clone a specific major.minor version branch +git clone -b 6.1 https://github.com/plone/buildout.coredev cd buildout.coredev ``` @@ -134,7 +146,7 @@ To login, the default credentials are the following. - password: `admin` -## Use the correct branch +## Work with git ```{important} This section applies to members of the GitHub `plone/developers` team, who have write access to repositories under the Plone GitHub organization. @@ -142,9 +154,6 @@ This section applies to members of the GitHub `plone/developers` team, who have Members of the `plone/contributors` team do not have write access, and instead must follow the process to set up their remote upstream and origin branches as described in {ref}`set-up-your-environment-label`. ``` -The current default and development branch of `buildout.coredev` is `6.1`. -Older versions are named according to their `major.minor` version. - Always begin by checking out the git branch on which you want to work. If you have not yet checked out a branch, then you need to track it with the `-t` option and specify the remote to track, usually called `origin`. The following command will switch and track changes from the remote `origin` and its branch `6.1`. @@ -153,7 +162,7 @@ The following command will switch and track changes from the remote `origin` and git checkout -t origin/6.1 ``` -If you check out a different branch, and want to return to the previous branch, you need to specify only the local branch. +Now going forward, you need to specify only the local branch when you want to switch back to it from your development branch. ```shell git checkout 6.1 @@ -165,11 +174,7 @@ Next pull down and merge any recent changes from the remote tracked repository w git pull ``` -```{important} -Make sure to rerun buildout for the current branch to get the correct versions of packages, otherwise you will get some weird behavior. -``` - -Next create a new branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. +Next create a new development branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. ```shell From 1704bbc84217f255ac9716aad06f2c0241588f89 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:27:16 -0700 Subject: [PATCH 25/69] Move new development branch under Edit packages, and use what @thet and I walked through, now that it all makes sense (for now) --- docs/contributing/core/index.md | 53 ++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index d8bbfc85e7..8f19de2e03 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -174,15 +174,6 @@ Next pull down and merge any recent changes from the remote tracked repository w git pull ``` -Next create a new development branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. -It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. - -```shell -git switch -c 123-thing-i-fixed -t origin/6.1 -``` - -Now you can edit your code without affecting the original branch. - ## Edit packages @@ -190,33 +181,53 @@ First identify the names of the Plone packages you want to work on. If you do not know, you can ask in the [Plone Community Forum](https://community.plone.org/). Only a few packages are in {file}`src/` by default. -Edit the file {file}`checkouts.cfg` at the root of the repository by adding the package names under the `auto-checkout` list. +Next create a new file {file}`buildout.local.cfg`, and add the names of packages that you want to develop under the `auto-checkout` list. -```{code-block} cfg -:emphasize-lines: 10- +```cfg [buildout] -always-checkout = force -# always-checkout = false +extends = + buildout.cfg + auto-checkout = -# These packages are always checked out: - docs - # -# These packages are manually added, or automatically added by mr.roboto: - # + # Add packages that you want to develop plone.app.event icalendar + # others + ... ``` -Then rerun buildout to install the source packages to edit. +When you make changes in your package, then rerun buildout with the following command, specifying your new buildout configuration file with the `-c` option. ```shell -./bin/buildout +./bin/buildout -c buildout.local.cfg ``` ```{seealso} For tips on working with `mr.developer`, see {doc}`mrdeveloper`. ``` +````{tip} +To avoid conflicts with `buildout.coredev` files, you can configure git for your user. +Either create or edit a file at {file}`~/.gitconfig`. +Then add the following stanza to it. + +```cfg +[core] + excludesfile = ~/.gitignore_global +``` + +Then add any standard `.gitignore` syntax to exclude files from getting committed and pushed to a remote repository. +```` + +Next create a new development branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. +It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. + +```shell +git switch -c 123-thing-i-fixed -t origin/6.1 +``` + +Now you can edit your code without affecting the original branch. + ## Test locally From 7e604ed4df2c597436d9c1a1e7f8a656fb1ac31f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:30:12 -0700 Subject: [PATCH 26/69] Add -N flag option to buildout --- docs/contributing/core/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 8f19de2e03..49387bfb0d 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -197,9 +197,10 @@ auto-checkout = ``` When you make changes in your package, then rerun buildout with the following command, specifying your new buildout configuration file with the `-c` option. +You can add the `-N` flag to save time by not checking PyPI to see if there are updates to packages that were already installed. ```shell -./bin/buildout -c buildout.local.cfg +./bin/buildout -c buildout.local.cfg -N ``` ```{seealso} From fcdd9923dcb60a1007cea70e2ebf9c3bdf73544d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:45:17 -0700 Subject: [PATCH 27/69] Reference tests to use PR, CI, and Jenkins first, and locally only if necessary --- docs/contributing/core/index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 49387bfb0d..2b1b73f895 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -237,13 +237,15 @@ If you change the expected behavior of a feature in a package, you should write To run a test for the specific package that you modified, use the `-m` option followed by the package name, as shown in the following example. ```shell -./bin/test -m plone.app.caching +./bin/test -m plone.app.event ``` If any test fails, do not commit and push the changes. Instead write a test that passes. -After the package level tests pass with your change, you can run the full unit test suite to ensure other packages aren't affected by the change. +After the package level tests pass with your change, you can {ref}`contributing-core-create-a-pull-request-label` and let CI run and ask Jenkins to run the full test suite. + +However, if CI or Jenkins report a test failure that you want to troubleshoot locally, you can run the full unit test suite to ensure other packages aren't affected by the change. It takes 5-10 minutes to run the full unit test suite. ```shell @@ -284,6 +286,8 @@ The Plone release manager will check this file to see which packages you have up ``` +(contributing-core-create-a-pull-request-label)= + ## Create a pull request After you have completed all the foregoing steps, push your changes to a remote branch and create a pull request in GitHub. From 7838b17d1b3a529800d30b4cae2d6cfd1c01d87c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:46:51 -0700 Subject: [PATCH 28/69] Add note for how to identify towncrier repos --- docs/contributing/core/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 2b1b73f895..013912c14f 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -268,6 +268,7 @@ If you can't afford this disruption, you can defer it to Jenkins. All changes require a change log entry. For packages that use [towncrier](https://pypi.org/project/towncrier/) to produce change logs, see {ref}`contributing-change-log-label`. +A package that uses towncrier has a `news` directory at its repository or package root. For packages that don't use towncrier, edit either {file}`CHANGES.rst`, {file}`CHANGES.txt`, or {file}`HISTORY.txt` in each package you have modified, adding a summary of the change. New change log entries should be added at the top of {file}`CHANGES.rst`. From abf5f7b4dadf5556cd1abe8533970eb3c083bcc6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:47:49 -0700 Subject: [PATCH 29/69] Remove obsolete section "Update `checkouts.cfg`" --- docs/contributing/core/index.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 013912c14f..5a545e36d0 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -274,19 +274,6 @@ For packages that don't use towncrier, edit either {file}`CHANGES.rst`, {file}`C New change log entries should be added at the top of {file}`CHANGES.rst`. -## Update `checkouts.cfg` - -If you didn't do so earlier, edit the file {file}`checkouts.cfg` at the root, and add your changed packages only to the `auto-checkout` list. -Remove any packages that you previously added to this file, but did not change. -Leave any pre-existing packages in the original list. - -The Plone release manager will check this file to see which packages you have updated to make a proper release. - -```{seealso} -{doc}`release` -``` - - (contributing-core-create-a-pull-request-label)= ## Create a pull request From bc12737979848953a97e6aa2b9e18d236171b14e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:53:33 -0700 Subject: [PATCH 30/69] Copy from first-time-contributors about Fixes #ISSUE-NUMBER --- docs/contributing/core/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 5a545e36d0..7ddf2b46e8 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -279,8 +279,9 @@ New change log entries should be added at the top of {file}`CHANGES.rst`. ## Create a pull request After you have completed all the foregoing steps, push your changes to a remote branch and create a pull request in GitHub. - -If you are working from an issue, return to the original issue, and add a link to the pull request. +If you are working from an issue, include "Fixes #ISSUE-NUMBER" in the description. +This enables automatic closing of the related issue when the pull request is merged. +This also creates a hyperlink to the original issue for easy reference. ## Jenkins and mr.roboto From 6ef5c58872b6b68c76a8563c41a38b506ded8496 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 24 Jun 2024 04:57:07 -0700 Subject: [PATCH 31/69] Purge obsolete explanation about what Jenkins runs --- docs/contributing/core/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 7ddf2b46e8..fbf4b85be2 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -291,8 +291,6 @@ Plone has a continuous integration ({term}`CI`) setup and follows CI rules. When you push a change to a Plone package, there may be GitHub workflows that run automatically. The CI package [mr.roboto](https://github.com/plone/mr.roboto) will perform some checks and suggest that you run Jenkins after all other CI runs. -For each Plone and Python version, Jenkins runs two jobs: one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are affected by your change). - See {doc}`continuous-integration` for more information. From 21e36586b703d0647f55783f9347134d1a857643 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 01:04:56 -0700 Subject: [PATCH 32/69] Update C compiler pre-requisites Co-authored-by: David Glick --- docs/contributing/core/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index fbf4b85be2..26fb0aab44 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -64,9 +64,9 @@ Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. ### C compiler -You need a C compiler on your system to compile {term}`ZODB` and {term}`Zope`. +You need a C compiler on your system to compile some of the Python libraries that Plone uses. -On macOS, Developer Tools providers clang for a C compiler. +On macOS, Developer Tools provides Clang for a C compiler. On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common option. From a80c9ccc6fb197b567e6dcc8e62d3be5164d96e0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 01:48:48 -0700 Subject: [PATCH 33/69] Reword seealso for `mr.developer` --- docs/contributing/core/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 26fb0aab44..016216316a 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -204,7 +204,8 @@ You can add the `-N` flag to save time by not checking PyPI to see if there are ``` ```{seealso} -For tips on working with `mr.developer`, see {doc}`mrdeveloper`. +`mr.developer` checks out additional repositories using the `auto-checkout` option. +For more information, see {doc}`mrdeveloper`. ``` ````{tip} From 26da8cc1d6fed9aa0adb12611384c29546c77e9e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 02:01:08 -0700 Subject: [PATCH 34/69] Rewrite adn simplify git pieces --- docs/contributing/core/index.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 016216316a..add4d7a419 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -155,14 +155,9 @@ Members of the `plone/contributors` team do not have write access, and instead m ``` Always begin by checking out the git branch on which you want to work. -If you have not yet checked out a branch, then you need to track it with the `-t` option and specify the remote to track, usually called `origin`. -The following command will switch and track changes from the remote `origin` and its branch `6.1`. +This is the base branch to which you will create a pull request. -```shell -git checkout -t origin/6.1 -``` - -Now going forward, you need to specify only the local branch when you want to switch back to it from your development branch. +If you just cloned `https://github.com/plone/buildout.coredev`, then the `6.1` branch is checked out and current, and you can skip the rest of this section and continue on the next, {ref}`contributing-core-edit-packages-label`. ```shell git checkout 6.1 @@ -175,6 +170,8 @@ git pull ``` +(contributing-core-edit-packages-label)= + ## Edit packages First identify the names of the Plone packages you want to work on. @@ -225,7 +222,7 @@ Next create a new development branch on which you want to work from the current It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. ```shell -git switch -c 123-thing-i-fixed -t origin/6.1 +git switch -c 123-thing-i-fixed ``` Now you can edit your code without affecting the original branch. From 6f816aeef2e825a521d45e959fca834d4bae3718 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 03:33:27 -0700 Subject: [PATCH 35/69] Indicate symbol --- docs/contributing/core/mrdeveloper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/mrdeveloper.md b/docs/contributing/core/mrdeveloper.md index db4b0aabf7..114bf9379d 100644 --- a/docs/contributing/core/mrdeveloper.md +++ b/docs/contributing/core/mrdeveloper.md @@ -27,7 +27,7 @@ From time to time you can check if some old cruft has accumulated. bin/develop status ``` -If this prints any lines with a question mark in front, you can clean the cruft with the following command. +If this prints any lines with a question mark (`?`) in front, you can clean the cruft with the following command. ```shell bin/develop purge From 4a269ca060c982b1bf8935ee04c2775ea3e6e91f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 03:35:46 -0700 Subject: [PATCH 36/69] Fix headings and meta information --- docs/contributing/core/documentation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contributing/core/documentation.md b/docs/contributing/core/documentation.md index 70f3b299da..ff06f57cf7 100644 --- a/docs/contributing/core/documentation.md +++ b/docs/contributing/core/documentation.md @@ -1,13 +1,13 @@ --- myst: html_meta: - "description": "Writing documentation of Plone" - "property=og:description": "Writing documentation of Plone" - "property=og:title": "Writing documentation of Plone" + "description": "Write documentation of Plone" + "property=og:description": "Write documentation of Plone" + "property=og:title": "Write documentation of Plone" "keywords": "documentation, Plone" --- -# Writing documentation +# Write documentation For general guidance for contributing documentation, see {doc}`/contributing/documentation/index`. @@ -20,7 +20,7 @@ The documentation repository is on [GitHub](https://github.com/plone/documentati Information for how to contribute to documentation can be found at {doc}`/contributing/documentation/index`. -## Documenting a package +## Document a package At the very least, your package should include the following forms of documentation. From c8edc3c0b985434ba009551651ebd477bc8f34fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 03:37:05 -0700 Subject: [PATCH 37/69] Remove todo --- docs/contributing/core/plips.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index ef1a5cce3f..83da6d27ee 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -9,13 +9,6 @@ myst: # Plone Improvement Proposals (PLIPs) -```{todo} -This page needs extensive review. -It is not clear whether the Framework Team still exists, and PLIPs are now spread over many repositories. - -See https://community.plone.org/t/plips-documentation/19609 -``` - A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone who uses that package. PLIPs go through a formal process compared to bug fixes because of their broad reach. The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. From 86c1fcac807a5c71f1e9990dd00c97d35572159f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 04:00:02 -0700 Subject: [PATCH 38/69] - Align overview with sections of PLIP submittal process - Add designated packages, teams, repos with a default --- docs/contributing/core/plips.md | 48 ++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 83da6d27ee..3b8c13e6df 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -16,21 +16,35 @@ The Plone Framework Team reviews all PLIPs to make sure that it's in the best in ## Process overview -1. Developer submits a PLIP. -2. [SOME_INDETERMINATE_TEAM] approves the PLIP for inclusion into Plone core for a given release. -3. Developer implements the PLIP, including code, tests, and documentation. -4. Developer creates a pull request of the PLIP for review by the [SOME_INDETERMINATE_TEAM]. -5. [SOME_INDETERMINATE_TEAM] reviews the PLIP and gives feedback. -6. Developer addresses concerns from the feedback, and resubmits the PLIP, if necessary. -7. Repeat the two previous steps, until both the [SOME_INDETERMINATE_TEAM] and developer are happy with the result. -8. [SOMEBODY] approves the PLIP for merge. -9. [SOMEBODY] merges the PLIP. +1. Developer submits a PLIP and solicits feedback. +2. Developer addresses concerns from the feedback, and resubmits the PLIP, if necessary. +3. The designated team approves the PLIP for inclusion into Plone core for a given release. +4. Developer implements the PLIP, including code, tests, and documentation. +5. Developer creates a pull request of the PLIP for review by the designated team. +6. The designated team reviews the pull request of the PLIP and gives feedback. +7. Repeat the two previous steps, until both the designated team and developer are happy with the result. +8. A designated team member approves the PLIP for merge. +9. A designated team member merges the PLIP. In rare circumstances, a PLIP may be rejected. This is usually the result of the developer not responding to feedback or dropping out of the process. -(submit-a-plip)= +(designated-teams-label)= + +## Designated teams + +The following packages and repositories have designated teams that you can contact by `@`-ing them in its GitHub issue tracker. +If the repository is not listed, use the default repository for `Products.CMFPlone`. + +| Package | Repository | Team | +|---|---|---| +| `Products.CMFPlone` | https://github.com/plone/Products.CMFPlone | not applicable | +| Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | +| Volto | https://github.com/plone/volto | `@plone/volto-team` | + + +(submit-a-plip-label)= ## Submit a PLIP @@ -61,16 +75,22 @@ Now that you are prepared, submit your PLIP. 4. When done, click {guilabel}`Submit new issue` to submit your PLIP. -5. If it does not automatically assign the label {guilabel}`03 type: feature (plip)`, then assign that label to the issue to make it easier to find. +5. If GitHub does not automatically assign the label {guilabel}`03 type: feature (plip)`, then assign that label to the issue to make it easier to find. ## Get feedback -After you submit your PLIP, solicit feedback for your idea on the [Plone Community Forum](https://community.plone.org/). +After you submit your PLIP, solicit feedback for your idea on the [Plone Community Forum](https://community.plone.org/) and through the repository's issue tracker. You may revise your PLIP based on feedback. -If you need help at any point in this process, please contact a member of the [SOME_INDETERMINATE_TEAM] personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team/12). +If you need help at any point in this process, you can either `@` the team or personally contact a member of the designated team. + + +## Team approves proposal + +After incorporating feedback to your proposal, you can request a final review and approval for inclusion in Plone. +Every PLIP must be approved by the designated team. ## Implement your PLIP @@ -260,5 +280,3 @@ In general, PLIPs shouldn't take more than a year, otherwise they should be clos If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. It is often the case that there are competing implementations, and the community wants to see it vetted as an add-on before "blessing" a particular implementation. - - From 33156c306ac8ef2c3358c4ad7ca5dde8b9dea7be Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 04:34:45 -0700 Subject: [PATCH 39/69] - Purge FAQ as redundant and unused. No one asks questions about PLIPs anyway, so how can they be frequent? - Purge hand-holding. It's a how-to guide. - Refer to setup of development environment. --- docs/contributing/core/index.md | 6 +- docs/contributing/core/plips.md | 150 ++++++-------------------------- 2 files changed, 32 insertions(+), 124 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index add4d7a419..0041f82296 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -180,7 +180,7 @@ Only a few packages are in {file}`src/` by default. Next create a new file {file}`buildout.local.cfg`, and add the names of packages that you want to develop under the `auto-checkout` list. -```cfg +```ini [buildout] extends = buildout.cfg @@ -228,6 +228,8 @@ git switch -c 123-thing-i-fixed Now you can edit your code without affecting the original branch. +(contributing-core-test-locally-label)= + ## Test locally If you change the expected behavior of a feature in a package, you should write a test to cover the change. @@ -261,6 +263,8 @@ If you can't afford this disruption, you can defer it to Jenkins. ``` +(contributing-core-change-log-label)= + ## Change log All changes require a change log entry. diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 3b8c13e6df..c369b53293 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -95,6 +95,12 @@ Every PLIP must be approved by the designated team. ## Implement your PLIP +(plip-setup-instructions-label)= + +```{note} +This section assumes you have read and followed the instructions in {doc}`index` to set up your development environment, up until {ref}`contributing-core-edit-packages-label`. +``` + You can start the development at any time, but if you intend to modify Plone core, it is a good idea to wait to see if your idea is approved. @@ -114,15 +120,12 @@ You can start the development at any time, but if you intend to modify Plone cor ### Create a new PLIP branch -Create a buildout configuration file for your PLIP in the `plips` folder of {file}`buildout.coredev`. - -Give it a descriptive name, starting with the PLIP number, for example, {file}`plip-1234-widget-frobbing.cfg`. +Create a buildout configuration file for your PLIP in the `plips` folder of `buildout.coredev`. +Its name should follow the pattern `plip-repository-issue_number-description.cfg`. +For example, {file}`plip-volto-1234-widget-frobbing.cfg`. -The PLIP number is your PLIP's issue number. - -This file will define the branches you're working with in your PLIP, along with other buildout configuration. - -It should look something like the following, such as in a file {file}`plips/plip-1234-widget-frobbing.cfg`. +This file will define the branches for your PLIP, along with other buildout configuration. +The following is example content for the file {file}`plips/plip-volto-1234-widget-frobbing.cfg`. ```ini [buildout] @@ -132,8 +135,8 @@ auto-checkout += plone.app.someotherpackage [sources] -plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-1234-widget-frobbing -plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-1234-widget-frobbing +plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-volto-1234-widget-frobbing +plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-volto-1234-widget-frobbing [instance] eggs += @@ -145,138 +148,39 @@ zcml += ``` Use the same naming convention when you branch existing packages. -You should always branch packages when working on PLIPs. -### Working on a PLIP +### Work on a PLIP -To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: +To work on a PLIP, assuming you have followed the {ref}`PLIP set up instructions `, you can invoke buildout with your PLIP configuration as follows. ```shell -virtualenv . -./bin/pip install -r requirements.txt -./bin/buildout -c plips/plip-1234-widget-frobbing.cfg +./bin/buildout -c plips/plip-volto-1234-widget-frobbing.cfg ``` -If you are using a {file}`local.cfg` to extend your PLIP file with some changes that you do not want to commit accidentally, be aware that you need to override some settings from {file}`plipbase.cfg` to avoid some files being created in the {file}`plips` directory or in the directory above the buildout directory. -This is done as shown below. - -```ini -[buildout] -extends = plips/plip-1234-widget-frobbing.cfg -develop-eggs-directory = ./develop-eggs -bin-directory = ./bin -parts-directory = ./parts -sources-dir = ./src -installed = .installed.cfg - -[instance] -var = ./var +```{seealso} +See {ref}`contributing-core-test-locally-label`, {ref}`contributing-core-change-log-label`, and {ref}`contributing-core-create-a-pull-request-label`. ``` -### Finishing up +### Finish up -Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. -This file should be called {file}`plip__notes.txt`. +Before marking your PLIP as ready for review as a pull request, add a file to give a set of instructions to the PLIP reviewer. +This file should be called {file}`plip___notes.txt`. This should include, but is not limited to: -- URLs pointing to all documentation created and updated -- Any concerns and issues still remaining -- Any weird buildout things +- URLs pointing to all documentation created and updated +- Any concerns and issues still remaining +- Any weird buildout things -Once you have finished, update your PLIP issue to indicate that it is ready for review. -The Framework Team will assign 2-3 people to review your PLIP. +Once you have finished, update your PLIP issue and pull request to indicate that it is ready for review. +The designated team will review your PLIP. They will follow the guidelines listed at {doc}`plip-review`. -After the PLIP has been accepted by the Framework Team and the release managers, you will be asked to merge your work into the main development line. -Merging the PLIP in is not the hardest part, but you must think about it when you develop. - -You'll have to interact with a large number of people to get it all set up. +After the PLIP has been accepted by the designated team and the release managers, you will be asked to merge your work into the main development line. The merge may have unintended interactions with other PLIPs coming in. During the merge phase you must be prepared to help out with all the features and bugs that arise. If all went as planned, the next Plone release will carry on with your PLIP in it. You'll be expected to help out with that feature after it's been released (within reason). - - -## Frequently asked questions about PLIPs - -This section provides detailed answers to common questions about PLIPs. - - -### PLIP or bug fix? - -In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. -When in doubt, submit it as a PLIP. -The Framework Team will reclassify it if your proposal falls below the threshold. -If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. -The key point here is that each change must be documented, allowing it to be tracked and understood. - - -### Who can submit PLIPs? - -Anyone who has signed a Plone Contributor Agreement can work on a PLIP. - -```{todo} -The FWT no longer participates in PLIPs. -Recommend deletion of next two paragraphs. -``` -The Framework Team is happy to help you at any point in the process. - -When the PLIP is accepted, a Framework Team member will "champion" your PLIP and follow up to its completion. - - -### What is a PLIP champion? - -```{todo} -This section is no longer in practice. -Recommend deletion. -``` - -When you submit your PLIP and it is approved, a Framework Team member will take on the role of champion for that PLIP. - -They are there to help you through completion, answer questions, and provide guidance. - -A champion fulfills the following tasks: - -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. - -Keep in mind that champions are volunteers as well, and have other tasks in life. -That means you will have to play an active role in asking for help or guidance. - - -### Can I get involved in other ways? - -If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. - -Check the status of PLIPs at https://github.com/search?q=path%3A%2Fplone+label%3A%2203+type%3A+feature+%28plip%29%22++&type=issues&ref=advsearch&state=open. - -Then, follow the instructions for {doc}`reviewing a PLIP `. - - -### When can I submit a PLIP? - -Today, tomorrow, any time! - -After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. - - -### When is the PLIP due? - -**Summary: As soon as you get it done.** - -Ideally, a PLIP should be completed for the release to which it's assigned. -Sometimes life gets in the way, and a PLIP may have to be re-assigned to the following release. - -In general, PLIPs shouldn't take more than a year, otherwise they should be closed. A new PLIP can follow up if there is more capacity to see it through. - - -### What happens if your PLIP is not accepted? - -If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. -It is often the case that there are competing implementations, and the community wants to see it vetted as an add-on before "blessing" a particular implementation. From 33159051bccef69bd63ec0bb37fdccc14771d321 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 26 Jun 2024 04:56:29 -0700 Subject: [PATCH 40/69] Volto has its own contributing process, regardless of whether it is a PLIP --- docs/contributing/core/plips.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index c369b53293..091ca2e8dd 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -97,6 +97,11 @@ Every PLIP must be approved by the designated team. (plip-setup-instructions-label)= +```{important} +This section does not apply to Volto. +Instead see {doc}`../../volto/contributing/index`. +``` + ```{note} This section assumes you have read and followed the instructions in {doc}`index` to set up your development environment, up until {ref}`contributing-core-edit-packages-label`. ``` @@ -113,9 +118,7 @@ You can start the development at any time, but if you intend to modify Plone cor - Have clear code. - Follow current best practices in coding style. The [Plone Meta](https://github.com/plone/meta) project can help you set up your environment. - For Volto, follow {doc}`/volto/contributing/linting`. - [Be tested](https://5.docs.plone.org/develop/testing/index.html). - For Volto, follow {doc}`/volto/contributing/testing`. ### Create a new PLIP branch From f087267fce5a202a5b27885c41f39c89045a687f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 04:40:38 -0700 Subject: [PATCH 41/69] Add intersphinx configuration for Plone 5 docs --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index a5a763de42..a1f2ff9841 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -202,6 +202,7 @@ # the entire Plone Documentation is built. intersphinx_mapping = { "plone": ("https://6.docs.plone.org/", None), # for imported packages + "plone5": ("https://5.docs.plone.org/", None), "python": ("https://docs.python.org/3/", None), "training": ("https://training.plone.org/", None), "training-2022": ("https://2022.training.plone.org/", None), From 2098aa77ec4b83ecd40435b9c3cc09f3e71540fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 04:44:32 -0700 Subject: [PATCH 42/69] Finalize PLIP stuff --- docs/contributing/core/plip-review.md | 80 +++++++++++++-------------- docs/contributing/core/plips.md | 2 +- 2 files changed, 38 insertions(+), 44 deletions(-) diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md index aa979067dd..4ec0c0184d 100644 --- a/docs/contributing/core/plip-review.md +++ b/docs/contributing/core/plip-review.md @@ -10,25 +10,19 @@ myst: # PLIP review A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. +A review of a PLIP ensures that proposed behavior has been implemented as expected. +Post your PLIP review as a comment in the PLIP pull request. -## Expectations -A good PLIP review takes about four hours. -Please plan accordingly. - -When you are done, if you have access to core, commit the review to the `plips` folder of [`buildout.coredev`](https://github.com/plone/buildout.coredev), and reference the PLIP in your commit message. -If you do not have access, attach your review to the PLIP ticket itself. - - -## Setting up the environment +## Set up the environment Follow the instructions in {doc}`index`. You will need to checkout the branch to which the PLIP is assigned. Instead of running the buildout with the default buildout file, you will run the configuration specific to that PLIP: ```shell -./bin/buildout -c plips/plip-XXXX.cfg +./bin/buildout -c plips/plip---.cfg ``` @@ -36,81 +30,81 @@ Instead of running the buildout with the default buildout file, you will run the This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. +Report bugs or issues you find during the review on GitHub as you would for any Plone bug. +Reference the PLIP in the bug, assign it to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. +This way the implementer can find help if they need it. +Also set a priority for the ticket. +The PLIP will not be merged until all blockers and critical bugs are fixed. + ### General +- Take screenshots or videos as necessary, and post them to the pull request with your comments. - Does the PLIP actually do what the implementers proposed? - Are there incomplete variations? +- Are there incomplete variations? - Were there any errors running buildout? - Did the migration(s) work? +- If there were migrations, did they work? - Do error and status messages make sense? - Are they properly internationalized? +- Are messages properly internationalized? - Are there any performance considerations? - Has the implementer addressed them, if so? ### Bugs - Are there any bugs? - Nothing is too big nor small. -- Do fields handle wacky data? - How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? - Is it too restrictive or not restrictive enough? +- Do fields handle unexpected data? +- Is validation function correctly and make sense? +- Is validation too restrictive or not restrictive enough? -### Usability Issues +### Usability issues - Is the implementation usable? -- How will novice end users respond to the change? +- How will end users respond to the change? - Does this PLIP need a usability review? - If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. + If you think this PLIP needs a usability review, add GitHub issue labels {guilabel}`99 tag: UX`, or similar, and {guilabel}`32 needs: review`, and add a note in the comments. - Is the PLIP consistent with the rest of Plone? For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? - Is there any workflow that feels odd? +- Does everything flow nicely for all users? - Are there any new permissions and do they work properly? - Does their role assignment make sense? +- Does permission assignment to roles make sense? -### Documentation Issues +### Documentation issues -- Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? -- Is the change itself properly documented? +- Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? +- Is the change itself properly documented? -Report bugs or issues on GitHub as you would for any Plone bug. -Reference the PLIP in the bug, assign to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. -This way the implementer can find help if they need it. -Also set a priority for the ticket. -The PLIP will not be merged until all blockers and critical bugs are fixed. +## Code review -### Code Review +This section describes considerations of code quality. -#### Python +### Python - Is this code maintainable? - Is the code properly documented? -- Does the code adhere to PEP8 standards (more or less)? -- Are they importing deprecated modules? +- Does the code adhere to formatting and style standards? +- Are there any importied deprecated modules? -#### JavaScript +### JavaScript -- Does the JavaScript meet our set of JavaScript standards? - See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). +- Does the JavaScript satisfy the package's JavaScript standards, or if the package has no standard, then Plone's? + See Plone's section about {doc}`plone5:develop/addons/javascript/index` and the {doc}`plone5:develop/styleguide/javascript`. - Does the JavaScript work in all currently supported browsers? - Is it performant? +- Is the JavaScript performant? ```{todo} Update links from Plone 5 Documentation to Plone 6 Documentation, when they exist. See https://github.com/plone/documentation/issues/1330 ``` -#### ME/TAL +### ME/TAL - Does the PLIP use views appropriately, avoiding too much logic? - Is there any code in a loop that could potentially be a performance issue? - Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? +- Is the rendered HTML compliant with standards? +- Are `id`s and classes used appropriately? diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 091ca2e8dd..6941d6b555 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -118,7 +118,7 @@ You can start the development at any time, but if you intend to modify Plone cor - Have clear code. - Follow current best practices in coding style. The [Plone Meta](https://github.com/plone/meta) project can help you set up your environment. - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). + - Be tested according to Plone core's {doc}`plone5:develop/testing/index`. ### Create a new PLIP branch From 340a0ae4fdff46db8592f2bd2b50d4e0cee218c6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 05:06:58 -0700 Subject: [PATCH 43/69] Clean up release.md and add Community Forum posts --- docs/contributing/core/release.md | 92 ++++++++++++++++--------------- 1 file changed, 48 insertions(+), 44 deletions(-) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index 707e4eca95..7439d547ab 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -25,24 +25,25 @@ This command includes the following requirements. All files mentioned in this list may be written in Markdown or reStructuredText and have the appropriate file name suffix. ``` -- All releases must be hosted on PyPI. -- All versions must be tagged in version control. -- Each package must have a {file}`README` file with links to the version control repository and issue tracker. -- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. -- {file}`CHANGES` must contain release dates. -- {file}`README` and {file}`CHANGES` must be visible on PyPI. -- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. +- All releases must be hosted on PyPI. +- All versions must be tagged in version control. +- Each package must have a {file}`README` file with links to the version control repository and issue tracker. +- {file}`CHANGES` (or {file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. +- {file}`CHANGES` must contain release dates. +- {file}`README` and {file}`CHANGES` must be visible on PyPI. +- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. -- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). +- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template and `.po` files). ```{seealso} [High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). ``` + ## Special packages The Plone Release Team releases the core Plone packages. -Several others also have the rights to release individual packages on [PyPI](https://pypi.org/). +Several other people also have the rights to release individual packages on [PyPI](https://pypi.org). If you have those rights on your account, you should feel free to make releases. Some packages need special care, or should be done only by specific people, as they know what they are doing. @@ -54,13 +55,14 @@ These are: `plone.app.locales` : Please leave this to the i18n team lead, Vincent Fretin. + ## Plone core release process checklist -1. Check Jenkins status. - Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org/). +1. Check Jenkins status. + Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org). It should be green, but if it is not, fix the problem first. -2. Check out `buildout.coredev`. +1. Clone `buildout.coredev`, then check out and build the version to be released. ```shell git clone git@github.com:plone/buildout.coredev.git @@ -70,8 +72,8 @@ These are: bin/buildout -c buildout.cfg ``` -3. Check packages for updates. - Check all packages for updates, add to or remove from `checkouts.cfg` accordingly. +1. Check packages for updates. + Add to or remove from `checkouts.cfg` accordingly. This script may help: ```shell @@ -80,48 +82,50 @@ These are: This step should not be needed, because we do the check for every single commit, but people may still have forgotten to add a package to the `checkouts.cfg` file. -4. Check packages individually. +1. Check packages individually. Use the `bin/fullrelease` script from the core development buildout. This includes extra checks that we have added in `plone.releaser`. It guides you through all the next steps. - 1. Check changelog. + 1. Check changelog. Check if `CHANGES` is up-to-date. All changes since the last release should be included. A "Fixes" or "New" header should be included, with the relevant changes under it. Upgrade notes are best placed here as well. Compare `git log HEAD...` with `CHANGES`, or from `zest.releaser` use the command `lasttaglog `. - 2. Run [pyroma](https://pypi.org/project/pyroma/). - 3. Run [check-manifest](https://pypi.org/project/check-manifest/). - 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). - 5. Check if the version in `setup.py` is correct and follows our versioning best practice. - 6. Make a release (zest.releaser: `bin/fullrelease`) - 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. - -5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. -6. Update CMFPlone version in `profiles/default/metadata.xml`. -7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. -8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). - - 1. Copy all core packages there. - 2. Possibly make an alpha or beta release of CMFPlone. - 3. Copy the `versions.cfg` file from coredev to there. - -9. Write an email to the Plone developers list announcing a pending release. -10. Update `plone.app.locales` version. -11. Create a unified changelog. + 1. Run [pyroma](https://pypi.org/project/pyroma/). + 1. Run [check-manifest](https://pypi.org/project/check-manifest/). + 1. Check package "best practices" (`README`, `CHANGES`, `src` directory). + 1. Check if the version in `setup.py` is correct and follows our versioning best practice. + 1. Make a release with `zest.releaser`: `bin/fullrelease`. + 1. Remove packages from the `auto-checkout` section in `checkouts.cfg`, and update `versions.cfg`. + +1. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. +1. Update CMFPlone version in `profiles/default/metadata.xml`. +1. Create an issue in https://github.com/collective/plone.app.locales/issues to ask the i18n team lead `@vincentfretin` to do a `plone.app.locales` release. +1. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). + + 1. Copy all core packages there. + 1. Possibly make an alpha or beta release of CMFPlone. + 1. Copy the `versions.cfg` file from coredev to there. + +1. Write an email to the Plone developers list announcing a pending release. +1. Create a post on the Plone Community Forum announcing a pending release. +1. Update `plone.app.locales` version. +1. Create a unified changelog. ```shell bin/manage changelog ``` -12. Make the final release on [dist.plone.org](https://dist.plone.org/) (remove "-pending") -13. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). -14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). -15. Create a release page on [plone.org](https://plone.org/download/releases) -16. Wait for installers to be uploaded to Launchpad, with a link to the [plone.org](https://plone.org/download/releases) release page. -17. Publish release page on [plone.org](https://plone.org/). -18. Update [plone.org](https://plone.org/) homepage links to point to the new release. -19. Send out announcement to the plone-announce email distribution list. -20. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. +1. Make the final release on [dist.plone.org](https://dist.plone.org/) (remove "-pending") +1. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). +1. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). +1. Create a release page on [plone.org](https://plone.org/download/releases) +1. Wait for installers to be uploaded to Launchpad, with a link to the [plone.org](https://plone.org/download/releases) release page. +1. Publish release page on [plone.org](https://plone.org/). +1. Update [plone.org](https://plone.org/) homepage links to point to the new release. +1. Send out announcement to the plone-announce email distribution list for the final release. +1. Create a post on the Plone Community Forum announcing the final release. +1. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. From 693d0268cb269567b522c1547ff1eaa02674e75a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 05:23:17 -0700 Subject: [PATCH 44/69] Update troubleshooting.md --- docs/contributing/core/troubleshooting.md | 56 +++++++++++------------ 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/contributing/core/troubleshooting.md b/docs/contributing/core/troubleshooting.md index 7a08cfa170..724a77d206 100644 --- a/docs/contributing/core/troubleshooting.md +++ b/docs/contributing/core/troubleshooting.md @@ -1,55 +1,55 @@ --- myst: html_meta: - "description": "Troubleshooting development issues in Plone" - "property=og:description": "Troubleshooting development issues in Plone" - "property=og:title": "Troubleshooting development issues in Plone" - "keywords": "Troubleshooting, development issues, Plone" + "description": "Troubleshoot development issues in Plone" + "property=og:description": "Troubleshoot development issues in Plone" + "property=og:title": "Troubleshoot development issues in Plone" + "keywords": "Troubleshoot, development issues, Plone" --- -# Troubleshooting +# Troubleshoot This chapter describes how to troubleshoot development issues in Plone. + ## Buildout issues -Buildout can be frustrating for those unfamiliar with parsing through error messages. +This section describes issues you might experience with using buildout. -These errors are normally a quick fix. -### Errors running `bootstrap.py` +### `bootstrap.py` errors -You may not even get to running buildout, before you already get an error. -As example: +When attempting to run buildout via the {file}`bootstrap.py`, the script exits with a `VersionConflict` error message. ```shell File "/usr/local/lib/python2.6/site-packages/distribute-0.6.13-py2.6.egg/pkg_resources.py", line 556, in resolve - raise VersionConflict(dist,req) # XXX put more info here + raise VersionConflict(dist,req) pkg_resources.VersionConflict: (zc.buildout 1.5.1 (/usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg), Requirement.parse('zc.buildout==1.5.2')) ``` -Buildout has noticed that the version of buildout required by the file `bootstrap.py` you are trying to run does not match the version of buildout in your Python library. +Buildout has noticed that the version of buildout required by the file `bootstrap.py` does not match the version of buildout in your Python path. In the error above, your system has buildout 1.5.1 installed and the `bootstrap.py` file wants to run with 1.5.2. -To fix, you have a couple options. -First, you can force buildout to run with the version you already have installed by invoking the version tag. -This tells your Plone `bootstrap.py` file to play nicely with the version that you already have installed. -In the case of the error pasted above, that would be: +You have two options to resolve the issue. -```shell -python bootstrap.py --version=1.5.1 -``` +1. You can force buildout to run with the version you already have installed by invoking the version tag. + This tells your Plone {file}`bootstrap.py` file to play nicely with the version that you already have installed. + In the case of the error pasted above, that would be: -The other option is to delete your current egg and force the upgrade. -In the case of the error above, delete the egg the system currently has, for example: + ```shell + python bootstrap.py --version=1.5.1 + ``` -```shell -rm -rf /usr/local/lib/python3.10/site-packages/zc.buildout-1.5.1-py3.10.egg -``` +1. The other option is to delete your current egg and force the upgrade. + In the case of the error above, delete the egg the system currently has, for example: + + ```shell + rm -rf /usr/local/lib/python3.10/site-packages/zc.buildout-1.5.1-py3.10.egg + ``` -When you rerun bootstrap, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. + When you rerun {file}`bootstrap.py`, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. -Do one of those and re-run bootstrap. +Do one of those and re-run {file}`bootstrap.py`. -One other thing of note is that running bootstrap effectively ties that Python executable and all of its libraries to your buildout. -If you have several Python installs, and want to switch which Python is tied to your buildout, rerun `bootstrap.py` with the new Python (and then rerun buildout). +When you run {file}`bootstrap.py`, it effectively ties that Python executable and all of its libraries to your buildout. +If you have several Python installs, and want to switch which Python is tied to your buildout, rerun {file}`bootstrap.py` with the new Python, and then rerun buildout. From 2f8630496b01709593e078f0fe793f5cd636c473 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 05:25:00 -0700 Subject: [PATCH 45/69] Reorder navigation --- docs/contributing/core/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 0041f82296..eadada2786 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -301,10 +301,10 @@ See {doc}`continuous-integration` for more information. ```{toctree} :maxdepth: 1 +documentation continuous-integration mrdeveloper -documentation -troubleshooting +troubleshoot plips plip-review package-dependencies From 438b8ef9600f2339c00ac4b4de9b1c873f687049 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 05:25:22 -0700 Subject: [PATCH 46/69] Rename troubleshooting.md to troubleshoot.md --- docs/contributing/core/{troubleshooting.md => troubleshoot.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/contributing/core/{troubleshooting.md => troubleshoot.md} (100%) diff --git a/docs/contributing/core/troubleshooting.md b/docs/contributing/core/troubleshoot.md similarity index 100% rename from docs/contributing/core/troubleshooting.md rename to docs/contributing/core/troubleshoot.md From cd238fe82fd6171bdb3a8361e24b31f23bf49871 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 06:00:09 -0700 Subject: [PATCH 47/69] Replace @vincentfretin with @erral --- docs/contributing/core/release.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index 7439d547ab..a45f7336a1 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -53,7 +53,7 @@ These are: : Please leave these to the release managers, Eric Steele and Maurits van Rees. `plone.app.locales` -: Please leave this to the i18n team lead, Vincent Fretin. +: Please leave this to the i18n team lead, Mikel Larreategi, `@erral` on GitHub. ## Plone core release process checklist @@ -103,7 +103,7 @@ These are: 1. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. 1. Update CMFPlone version in `profiles/default/metadata.xml`. -1. Create an issue in https://github.com/collective/plone.app.locales/issues to ask the i18n team lead `@vincentfretin` to do a `plone.app.locales` release. +1. Create an issue in https://github.com/collective/plone.app.locales/issues to ask the i18n team lead `@erral` to do a `plone.app.locales` release. 1. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). 1. Copy all core packages there. From b5426e8e7da23766ff8bd6cfd89a4f4167bfa863 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 06:21:50 -0700 Subject: [PATCH 48/69] Add link to active PLIPs GitHub project board. --- docs/contributing/core/plips.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 6941d6b555..9ab7ffd104 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -13,6 +13,8 @@ A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package th PLIPs go through a formal process compared to bug fixes because of their broad reach. The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. +A project board of active PLIPs is located at https://github.com/orgs/plone/projects/47. + ## Process overview From 9df10b5e88b75dce67752adbe7df98b2b0683744 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:41:44 -0700 Subject: [PATCH 49/69] Update docs/contributing/core/index.md Co-authored-by: Maurits van Rees --- docs/contributing/core/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index eadada2786..6252b03b5c 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -105,6 +105,7 @@ Notice that the script expects Python 3.11 to be installed on your system and in ``` Edit it according to the Python version you want to use, then save and close the file. +After you have run the script you should undo the change, otherwise you have a local change in git that you might accidentally commit. ```` Now run the script to install Plone 6. From be8c6ad660b7c14108d719ec5ce8d7f2f1512c27 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:44:00 -0700 Subject: [PATCH 50/69] Fix doc link, grammar. --- docs/contributing/core/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 6252b03b5c..ced8bce212 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -105,7 +105,7 @@ Notice that the script expects Python 3.11 to be installed on your system and in ``` Edit it according to the Python version you want to use, then save and close the file. -After you have run the script you should undo the change, otherwise you have a local change in git that you might accidentally commit. +After you have run the script, you should undo the change, otherwise you have a local change in git that you might accidentally commit. ```` Now run the script to install Plone 6. @@ -114,7 +114,7 @@ Now run the script to install Plone 6. ./bootstrap.sh ``` -If you run into issues in this process, see {doc}`troubleshooting`. +If you run into issues in this process, see {doc}`troubleshoot`. This will run for a long time if it's your first pull (approximately 10-20 minutes, depending on network speed and your hardware). From 62072af5116247aa5d72b555877d92ae2d2794a9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:46:28 -0700 Subject: [PATCH 51/69] Use chromedriver and ROBOT_BROWSER environment variable Co-authored-by: Maurits van Rees --- docs/contributing/core/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index ced8bce212..0887d2f8e8 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -254,9 +254,12 @@ It takes 5-10 minutes to run the full unit test suite. ./bin/test ``` -If you run acceptance tests with the `--all` option, it will repeatedly launch and close browser windows that gain focus, disrupting you from doing any other work. +If you run acceptance tests with the `--all` option, it will run tests in a real browser. This takes 30-40 minutes to run. -If you can't afford this disruption, you can defer it to Jenkins. +This may repeatedly launch and close browser windows that gain focus, disrupting you from doing any other work. +If this happens, you can install the `chromedriver` OS package. +See https://developer.chrome.com/docs/chromedriver. +Then run `export ROBOT_BROWSER="headlesschrome"` and again run `bin/test --all`. ```shell # Run acceptance tests From a26ee569fca6bd160ade3990b6673c35ca6d00a1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:52:05 -0700 Subject: [PATCH 52/69] =?UTF-8?q?We=20don't=20use=20`bootstrap.py`.=20Burn?= =?UTF-8?q?=20it=20with=20=F0=9F=94=A5!?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contributing/core/index.md | 3 -- docs/contributing/core/release.md | 2 +- docs/contributing/core/troubleshoot.md | 55 -------------------------- 3 files changed, 1 insertion(+), 59 deletions(-) delete mode 100644 docs/contributing/core/troubleshoot.md diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 0887d2f8e8..664907983d 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -114,8 +114,6 @@ Now run the script to install Plone 6. ./bootstrap.sh ``` -If you run into issues in this process, see {doc}`troubleshoot`. - This will run for a long time if it's your first pull (approximately 10-20 minutes, depending on network speed and your hardware). Once that's done, you can start an instance of Plone with the following command. @@ -308,7 +306,6 @@ See {doc}`continuous-integration` for more information. documentation continuous-integration mrdeveloper -troubleshoot plips plip-review package-dependencies diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index a45f7336a1..c4082cc897 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -68,7 +68,7 @@ These are: git clone git@github.com:plone/buildout.coredev.git cd buildout.coredev git checkout 6.1 - python bootstrap.py + ./bootstrap.sh bin/buildout -c buildout.cfg ``` diff --git a/docs/contributing/core/troubleshoot.md b/docs/contributing/core/troubleshoot.md deleted file mode 100644 index 724a77d206..0000000000 --- a/docs/contributing/core/troubleshoot.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -myst: - html_meta: - "description": "Troubleshoot development issues in Plone" - "property=og:description": "Troubleshoot development issues in Plone" - "property=og:title": "Troubleshoot development issues in Plone" - "keywords": "Troubleshoot, development issues, Plone" ---- - -# Troubleshoot - -This chapter describes how to troubleshoot development issues in Plone. - - -## Buildout issues - -This section describes issues you might experience with using buildout. - - -### `bootstrap.py` errors - -When attempting to run buildout via the {file}`bootstrap.py`, the script exits with a `VersionConflict` error message. - -```shell - File "/usr/local/lib/python2.6/site-packages/distribute-0.6.13-py2.6.egg/pkg_resources.py", line 556, in resolve - raise VersionConflict(dist,req) - pkg_resources.VersionConflict: (zc.buildout 1.5.1 (/usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg), Requirement.parse('zc.buildout==1.5.2')) -``` - -Buildout has noticed that the version of buildout required by the file `bootstrap.py` does not match the version of buildout in your Python path. -In the error above, your system has buildout 1.5.1 installed and the `bootstrap.py` file wants to run with 1.5.2. - -You have two options to resolve the issue. - -1. You can force buildout to run with the version you already have installed by invoking the version tag. - This tells your Plone {file}`bootstrap.py` file to play nicely with the version that you already have installed. - In the case of the error pasted above, that would be: - - ```shell - python bootstrap.py --version=1.5.1 - ``` - -1. The other option is to delete your current egg and force the upgrade. - In the case of the error above, delete the egg the system currently has, for example: - - ```shell - rm -rf /usr/local/lib/python3.10/site-packages/zc.buildout-1.5.1-py3.10.egg - ``` - - When you rerun {file}`bootstrap.py`, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. - -Do one of those and re-run {file}`bootstrap.py`. - -When you run {file}`bootstrap.py`, it effectively ties that Python executable and all of its libraries to your buildout. -If you have several Python installs, and want to switch which Python is tied to your buildout, rerun {file}`bootstrap.py` with the new Python, and then rerun buildout. From 0d213ac3fdbf366018e1f75f735e65a2f9342b71 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:53:31 -0700 Subject: [PATCH 53/69] s/egg/package Co-authored-by: Maurits van Rees --- docs/contributing/core/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index c4082cc897..c6f1e6861b 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -33,7 +33,7 @@ All files mentioned in this list may be written in Markdown or reStructuredText - {file}`README` and {file}`CHANGES` must be visible on PyPI. - Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. -- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template and `.po` files). +- `.gitignore` and `MANIFEST.in` must reflect the files going in to the package (must include page template and `.po` files). ```{seealso} [High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). From 7b19bcb25d2b318e3edbc59f0b2c7bbd3e349302 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:54:53 -0700 Subject: [PATCH 54/69] Add maintainers Co-authored-by: Maurits van Rees --- docs/contributing/core/release.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index c6f1e6861b..8b6ccfce12 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -54,7 +54,11 @@ These are: `plone.app.locales` : Please leave this to the i18n team lead, Mikel Larreategi, `@erral` on GitHub. +`plone.staticresources`, `mockup`, `plonetheme.barceloneta`, `plone.classicui`: +: Please leave this to the Classic UI team, especially Peter Mathis, Johannes Raggam and Maik Derstappen. +`plone.restapi` and `plone.volto`: +: Please leave these to Timo Stollenwerk or David Glick. ## Plone core release process checklist From 4c7badf83102d9a816159af73be19faa9e3d03f0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 27 Jun 2024 17:59:04 -0700 Subject: [PATCH 55/69] Add GitHub handles to humans --- docs/contributing/core/release.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index 8b6ccfce12..723fb9cc46 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -53,12 +53,13 @@ These are: : Please leave these to the release managers, Eric Steele and Maurits van Rees. `plone.app.locales` -: Please leave this to the i18n team lead, Mikel Larreategi, `@erral` on GitHub. +: Please leave this to the i18n team lead, Mikel Larreategi `@erral`. `plone.staticresources`, `mockup`, `plonetheme.barceloneta`, `plone.classicui`: -: Please leave this to the Classic UI team, especially Peter Mathis, Johannes Raggam and Maik Derstappen. +: Please leave this to the Classic UI team, especially Peter Mathis `@petschki`, Johannes Raggam `@thet`, and Maik Derstappen `@MrTango`. `plone.restapi` and `plone.volto`: -: Please leave these to Timo Stollenwerk or David Glick. +: Please leave these to Timo Stollenwerk `@tisto` or David Glick `@davisagli`. + ## Plone core release process checklist From 75f782c13fde418ee429ba522429935ed82d982f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 03:50:27 -0700 Subject: [PATCH 56/69] Restore @plone/framework-team GitHub handle --- docs/contributing/core/plips.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 9ab7ffd104..a2b422bba1 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -41,7 +41,7 @@ If the repository is not listed, use the default repository for `Products.CMFPlo | Package | Repository | Team | |---|---|---| -| `Products.CMFPlone` | https://github.com/plone/Products.CMFPlone | not applicable | +| `Products.CMFPlone` | https://github.com/plone/Products.CMFPlone | `@plone/framework-team` | | Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | | Volto | https://github.com/plone/volto | `@plone/volto-team` | From 004370b6e7b18932af9cba683cc45072085bf030 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 03:51:25 -0700 Subject: [PATCH 57/69] s/FWT/designated team --- docs/contributing/core/plips.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index a2b422bba1..c523fba5f8 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -11,7 +11,7 @@ myst: A Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone who uses that package. PLIPs go through a formal process compared to bug fixes because of their broad reach. -The Plone Framework Team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. +A designated team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. A project board of active PLIPs is located at https://github.com/orgs/plone/projects/47. From 4c16ff270dc8056e50e72979785648cf87f310df Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 03:57:12 -0700 Subject: [PATCH 58/69] Update tips submodules/plone.api submodules/volto --- submodules/plone.api | 2 +- submodules/volto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/submodules/plone.api b/submodules/plone.api index b114c588c6..f29d2a178b 160000 --- a/submodules/plone.api +++ b/submodules/plone.api @@ -1 +1 @@ -Subproject commit b114c588c6b3b3984c2d682db4098912e87d0a48 +Subproject commit f29d2a178b51f659171c4f773fced1d9b3005d3e diff --git a/submodules/volto b/submodules/volto index 50bba48a54..ca3c293b23 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 50bba48a5468cd6c102b8e26dd62b55d1bb1e37b +Subproject commit ca3c293b2379dad38b52b0d8fa33e7ed87105f9c From d78a2d3e478783cb6434a9c2763e279b5b4521ee Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 04:33:35 -0700 Subject: [PATCH 59/69] Add a todo for the Steering Circle --- docs/contributing/core/plips.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index c523fba5f8..59143c0966 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -45,6 +45,7 @@ If the repository is not listed, use the default repository for `Products.CMFPlo | Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | | Volto | https://github.com/plone/volto | `@plone/volto-team` | +%TODO: PENDING CONTACT INFORMATION. If any team has issues with another team's PLIP, or if they have some ideas for PLIPs that could potentially impact other teams, then the Steering Circle is the first point of contact for coordination. If further action or coordination is required, then the Plone Foundation Board would be brought in. https://community.plone.org/t/plips-documentation/19609/14?u=stevepiercy (submit-a-plip-label)= From 7e741c889662893c4ee386621698fa3058104051 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 04:33:57 -0700 Subject: [PATCH 60/69] Add the PLIP to the PLIP project board --- docs/contributing/core/plips.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 59143c0966..32cff69597 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -80,6 +80,8 @@ Now that you are prepared, submit your PLIP. 5. If GitHub does not automatically assign the label {guilabel}`03 type: feature (plip)`, then assign that label to the issue to make it easier to find. +6. If GitHub does not automatically add the PLIP to the [PLIP project board](https://github.com/orgs/plone/projects/47), then add it so it can be tracked. + ## Get feedback From ad7dce19a7d0aeb131c860a81f33878a5f54bfb0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 29 Jun 2024 03:12:20 -0700 Subject: [PATCH 61/69] Remove TODO for Steering Circle, as it is not a relevant body to review PLIPs in a timely and effective manner, given it only meets monthly as a stand-up meeting --- docs/contributing/core/plips.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 32cff69597..c7b8b17ebb 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -45,7 +45,6 @@ If the repository is not listed, use the default repository for `Products.CMFPlo | Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | | Volto | https://github.com/plone/volto | `@plone/volto-team` | -%TODO: PENDING CONTACT INFORMATION. If any team has issues with another team's PLIP, or if they have some ideas for PLIPs that could potentially impact other teams, then the Steering Circle is the first point of contact for coordination. If further action or coordination is required, then the Plone Foundation Board would be brought in. https://community.plone.org/t/plips-documentation/19609/14?u=stevepiercy (submit-a-plip-label)= From add1c99653b4d6fcd2a5b3f10accba7f7b5478cf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 04:33:35 -0700 Subject: [PATCH 62/69] Add a todo for the Steering Circle --- docs/contributing/core/plips.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index c523fba5f8..59143c0966 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -45,6 +45,7 @@ If the repository is not listed, use the default repository for `Products.CMFPlo | Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | | Volto | https://github.com/plone/volto | `@plone/volto-team` | +%TODO: PENDING CONTACT INFORMATION. If any team has issues with another team's PLIP, or if they have some ideas for PLIPs that could potentially impact other teams, then the Steering Circle is the first point of contact for coordination. If further action or coordination is required, then the Plone Foundation Board would be brought in. https://community.plone.org/t/plips-documentation/19609/14?u=stevepiercy (submit-a-plip-label)= From ca03c8727a67bf9c53fde9aafb1fc44d18908579 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 28 Jun 2024 04:33:57 -0700 Subject: [PATCH 63/69] Add the PLIP to the PLIP project board --- docs/contributing/core/plips.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 59143c0966..32cff69597 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -80,6 +80,8 @@ Now that you are prepared, submit your PLIP. 5. If GitHub does not automatically assign the label {guilabel}`03 type: feature (plip)`, then assign that label to the issue to make it easier to find. +6. If GitHub does not automatically add the PLIP to the [PLIP project board](https://github.com/orgs/plone/projects/47), then add it so it can be tracked. + ## Get feedback From e5dae084c1d465c0e555655a85578e5fa76a14b6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 29 Jun 2024 03:12:20 -0700 Subject: [PATCH 64/69] Remove TODO for Steering Circle, as it is not a relevant body to review PLIPs in a timely and effective manner, given it only meets monthly as a stand-up meeting --- docs/contributing/core/plips.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md index 32cff69597..c7b8b17ebb 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -45,7 +45,6 @@ If the repository is not listed, use the default repository for `Products.CMFPlo | Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | | Volto | https://github.com/plone/volto | `@plone/volto-team` | -%TODO: PENDING CONTACT INFORMATION. If any team has issues with another team's PLIP, or if they have some ideas for PLIPs that could potentially impact other teams, then the Steering Circle is the first point of contact for coordination. If further action or coordination is required, then the Plone Foundation Board would be brought in. https://community.plone.org/t/plips-documentation/19609/14?u=stevepiercy (submit-a-plip-label)= From 113d9b36ed0fc8a2ac2c72876081780aca86971c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 29 Jun 2024 03:32:48 -0700 Subject: [PATCH 65/69] Revert "Update tips submodules/plone.api submodules/volto" This reverts commit 4c16ff270dc8056e50e72979785648cf87f310df. --- submodules/plone.api | 2 +- submodules/volto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/submodules/plone.api b/submodules/plone.api index f29d2a178b..b114c588c6 160000 --- a/submodules/plone.api +++ b/submodules/plone.api @@ -1 +1 @@ -Subproject commit f29d2a178b51f659171c4f773fced1d9b3005d3e +Subproject commit b114c588c6b3b3984c2d682db4098912e87d0a48 diff --git a/submodules/volto b/submodules/volto index ca3c293b23..50bba48a54 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit ca3c293b2379dad38b52b0d8fa33e7ed87105f9c +Subproject commit 50bba48a5468cd6c102b8e26dd62b55d1bb1e37b From 50f8fe16108a15aa9fdadc4655d0037aee3c2599 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 7 Jul 2024 07:58:59 -0700 Subject: [PATCH 66/69] Use `-s` for a package Co-authored-by: Gil Forcada Codinachs --- docs/contributing/core/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 664907983d..19f156d3dc 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -233,10 +233,10 @@ Now you can edit your code without affecting the original branch. If you change the expected behavior of a feature in a package, you should write a test to cover the change. -To run a test for the specific package that you modified, use the `-m` option followed by the package name, as shown in the following example. +To run a test for the specific package that you modified, use the `-s` option followed by the package name, as shown in the following example. ```shell -./bin/test -m plone.app.event +./bin/test -s plone.app.event ``` If any test fails, do not commit and push the changes. From 53e678bfe1a6ba9fca1ed8eeba7d3992466997c4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 7 Jul 2024 08:19:01 -0700 Subject: [PATCH 67/69] Fix typo Co-authored-by: Gil Forcada Codinachs --- docs/contributing/core/plip-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md index 4ec0c0184d..13d06d1ee9 100644 --- a/docs/contributing/core/plip-review.md +++ b/docs/contributing/core/plip-review.md @@ -86,7 +86,7 @@ This section describes considerations of code quality. - Is this code maintainable? - Is the code properly documented? - Does the code adhere to formatting and style standards? -- Are there any importied deprecated modules? +- Are there any imported deprecated modules? ### JavaScript From b4f87faafea09f340d68b0b8d12389bb44e0c080 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 20 Jul 2024 14:13:50 +0200 Subject: [PATCH 68/69] Comment out continuous-integration and silence Sphinx warning --- docs/conf.py | 1 + docs/contributing/core/index.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a1f2ff9841..13a8ca8af9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -125,6 +125,7 @@ "**/CONTRIBUTORS.rst", "**/LICENSE.rst", "**/README.rst", + "contributing/core/continuous-integration.md", "plone.restapi/.*", "plone.restapi/bin", "plone.restapi/docs/source/glossary.md", # There can be only one Glossary. diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 19f156d3dc..0a02f66910 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -295,7 +295,7 @@ Plone has a continuous integration ({term}`CI`) setup and follows CI rules. When you push a change to a Plone package, there may be GitHub workflows that run automatically. The CI package [mr.roboto](https://github.com/plone/mr.roboto) will perform some checks and suggest that you run Jenkins after all other CI runs. -See {doc}`continuous-integration` for more information. +%% See {doc}`continuous-integration` for more information. ## Additional material @@ -304,7 +304,7 @@ See {doc}`continuous-integration` for more information. :maxdepth: 1 documentation -continuous-integration +%% continuous-integration mrdeveloper plips plip-review From 73524a49289be792c51ff029cc21a95ed2e260b4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 20 Jul 2024 14:24:07 +0200 Subject: [PATCH 69/69] Purge coredev directory of now obsolete files --- coredev/agreement.md | 67 -- coredev/continous-integration.md | 109 ---- coredev/contributors_agreement_explained.md | 100 --- coredev/culture.md | 30 - coredev/documentation.md | 113 ---- coredev/getting-started-with-development.md | 391 ------------ coredev/git.md | 640 -------------------- coredev/guidelines.md | 57 -- coredev/index.md | 67 -- coredev/mrdeveloper.md | 40 -- coredev/packages-dependencies.md | 372 ------------ coredev/plip-review.md | 119 ---- coredev/plips.md | 299 --------- coredev/release.md | 136 ----- coredev/roboto.md | 63 -- coredev/troubleshooting.md | 186 ------ 16 files changed, 2789 deletions(-) delete mode 100644 coredev/agreement.md delete mode 100644 coredev/continous-integration.md delete mode 100644 coredev/contributors_agreement_explained.md delete mode 100644 coredev/culture.md delete mode 100644 coredev/documentation.md delete mode 100644 coredev/getting-started-with-development.md delete mode 100644 coredev/git.md delete mode 100644 coredev/guidelines.md delete mode 100644 coredev/index.md delete mode 100644 coredev/mrdeveloper.md delete mode 100644 coredev/packages-dependencies.md delete mode 100644 coredev/plip-review.md delete mode 100644 coredev/plips.md delete mode 100644 coredev/release.md delete mode 100644 coredev/roboto.md delete mode 100644 coredev/troubleshooting.md diff --git a/coredev/agreement.md b/coredev/agreement.md deleted file mode 100644 index a95b9a8cfe..0000000000 --- a/coredev/agreement.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -myst: - html_meta: - "description": "Contributing to Plone" - "property=og:description": "Contributing to Plone" - "property=og:title": "Contributing to Plone" - "keywords": "Contributing, Plone" ---- - -```{todo} -All this can go, it's redundant -``` - -(contributing-to-plone-label)= - -# Contributing to Plone - -There are many people and companies who rely on Plone on a day-to-day basis, so we must enforce some level of code quality control. - -Plone's source code is hosted in git repositories at , but only members of the developer team have commit rights. - -Sending in a contributors agreement does not guarantee your commit access to the repositories, but once you send it in we will always have it on file for when you are ready to contribute. - -We ask that before requesting core access you familiarize yourself a little with the community since they will help you get ramped up: - -- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. - -- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). - - There are plenty of opportunities to meet the community and start contributing through various coding sessions, either in person or on the web. - - You may even be able to get immediate core access at a conference if you are flexing your mad coding skills and the right people are attending. - -- Get your feet wet by contributing to the [collective](https://collective.github.io/). - Don't worry about getting it perfect or asking for help. - This way you get to know us and we improve our code together as a community. - -- **Patches:** Historically we encouraged people to submit patches to the ticket collector. - These tickets are usually ignored forever. - Technically, for us to accept your patch, you must sign the contributors agreement. - If you want to contribute fixes, please just sign the agreement and go through the standard GitHub pull request process described below until you feel comfortable to bypass review. - If the ticket is trivial, you do not need to sign a contributor's agreement. - -Once you have familiarized yourself with the community and you are excited to contribute to the core: - -- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . - This offers both copyright protection and ensures that the Plone Foundation is able to exercise some control over the codebase, ensuring it is not appropriated for someone's unethical purposes. - For questions about why the agreement is required, please see [About the Plone Contributor Agreement -](https://plone.org/foundation/contributors-agreement). - -If you aren't sure where to start or just want more direction, feel free to get in the forum or in chat, and ask for help. -While there is no official mentoring process, there are plenty of people willing to act in that role and guide you through the steps of getting involved in the community. -A common way to start contributing is to participate in a [Plone sprint](https://plone.org/news-and-events/events/sprints). - -**Welcome to the Plone community!** - - -## Dealing with pull requests on GitHub - -Before we can merge a pull request, we must ensure that the author has signed the Plone Contributor Agreement. - -If they're listed in either the [Developers](https://github.com/orgs/plone/teams/developers/members) or [Contributors](https://github.com/orgs/plone/teams/contributors/members) team, the author has signed the Plone Contributor Agreement, so we can go ahead and merge. - -If they aren't listed there, they may have signed and returned the Plone Contributor Agreement, but they were not yet added to a team. -You can ask agreements@plone.org to verify. - -Pull requests without a signed Plone Contributor Agreement can only be merged in trivial cases, and only by the release manager. diff --git a/coredev/continous-integration.md b/coredev/continous-integration.md deleted file mode 100644 index 49eb23d355..0000000000 --- a/coredev/continous-integration.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -myst: - html_meta: - "description": "Essential continuous integration practices" - "property=og:description": "Essential continuous integration practices" - "property=og:title": "Essential continuous integration practices" - "keywords": "Plone, continuous integration, best practices" ---- - -```{todo} -needs redaction and upgrade -``` - -# Essential continuous integration practices - -The CI system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code. - -Build breakages are a normal and expected part of the development process. -Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential rules that needs to be followed in order to achieve a stable build. - - -## 1) Don't check in on a broken build - -Do not make things more complicated for the developer who is responsible for breaking the build. - -If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it. -If we adopt this strategy, we will always be in the best position to find out what caused the breakage and fix it immediately. -If one of the developers has made a check-in and broken the build as a result, we have the best chance of fixing the build if we have a clear look at the problem. -Checking in further changes and triggering new builds will just lead to more problems. - -If the build is broken over a longer period of time (more than a couple of hours) you should either notify the developer who is responsible for the breakage, fix the problem yourself, or just revert the commit in order to be able to continue to work. - -```note -There is one exception to this rule. -Sometimes there are changes or tests that depend on changes in other packages. -If this is the case, there is no way around breaking a single build for a certain period of time. -In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. -``` - - -## 2) Always run all commit tests locally before committing - -Following this practice ensures the build stays green, and other developers can continue to work without breaking the first rule. - -There might be changes that have been checked in before your last update from the version control that might lead to a build failure in Jenkins in combination with your changes. -Therefore it is essential that you check out ({command}`git pull`) and run the tests again before you push your changes to GitHub. - -Furthermore, a common source of errors on check-in is to forget to add some files to the repository. - -If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system. - - -## 3) Wait for commit tests to pass before moving on - -Always monitor the build's progress, and fix the problem right away if it fails. -You have a far better chance of fixing the build, if you just introduced a regression than later. -Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours. - - -## 4) Never go home on a broken build - -Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially stops all other developers from working on it. -Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. -It will prevent all the other developers to stop working on the build or fixing the errors that you introduced. - - -## 5) Always be prepared to revert to the previous revision - -In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. - - -## 6) Time-box fixing before reverting - -When the build breaks on check-in, try to fix it for ten minutes. -If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. -This way you will allow other developers to continue to work. - - -## 7) Don't comment out failing tests - -Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. -While this impulse is understandable, it is **wrong**. - -The tests have been passing for a while and then start to fail. -This means that we either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason. - -You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). - - -## 8) Take responsibility for all breakages that result from your changes - -If you commit a change and all the tests you wrote pass, but others break, the build is still broken. -This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. -This means that you have introduced a regression bug into the application. - -It is **your responsibility**—because you made the change—to fix all tests that are not passing as a result of your changes. - -There are some tests in Plone that fail randomly, we are always working on fixing those. -If you think you hit such a test, try to fix it (better) or re-run the Jenkins job to see if it passes again. - -In any case the developer who made the commit is responsible to make it pass. - - -## Further Reading - -Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community. - -If you want to learn more about continuous integration and continuous delivery, I'd recommend that you buy this book. diff --git a/coredev/contributors_agreement_explained.md b/coredev/contributors_agreement_explained.md deleted file mode 100644 index ef04222b0b..0000000000 --- a/coredev/contributors_agreement_explained.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -myst: - html_meta: - "description": "Contributor's Agreement for Plone explained" - "property=og:description": "Contributor's Agreement for Plone explained" - "property=og:title": "Contributor's Agreement for Plone explained" - "keywords": "Contributor, Agreement, Plone" ---- - -```{todo} -All this can go, it's redundant -``` - -# Contributor's Agreement for Plone explained - -Prospective contributors to the Plone code base are required to sign a contributor's agreement, which assigns copyright in the code to the Plone Foundation, the non-profit organization which stewards the Plone code base. - -This document explains the purposes of this, along with questions and answers about what this means. - -The Plone Contributor's Agreement can be found at https://plone.org/foundation/contributors-agreement. - - -## About the Plone Contributor Agreement - -The Foundation feels that it benefits the community for a single organization to hold the rights to Plone. -Prior to the Foundation, the intellectual property of Plone was jointly held by individual developers and by Alan Runyan and Alexander Limi. - -The community members who formed the Foundation felt that having the Foundation hold these rights provides several benefits: - -1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. -2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. -3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. - - -## Questions and answers - -What does the Contributor's Agreement cover? - -> This agreement is for the Plone core codebase only. -> The Plone core codebase is that code which lives in the Plone core version repositories, currently located at [https://github.com/plone]. -> Contributions to the "Collective", currently located at [https://github.com/collective] are not assigned to the Plone Foundation, and are made available under whatever license the project developers wish to use, although add-on products that import from GPLed Plone code are of course subject to the terms of the GPL, which requires derived works to be GPL licensed. - -What rights will I continue to have for my contributions? - -> Contributors are asked to transfer their intellectual property rights to the Foundation. -> In return, they will be given back irrevocable rights to use and distribute their contributions. -> They can even give their contributions to other Open Source projects (as long as those projects are compatible with the license Plone itself is issued under) or use them in non-Open Source commercial applications (if that is compatible with the license Plone is under). - -Do I have to sign the contributor's agreement to make changes to the Plone core codebase? - -> Yes. - -Do I have to sign the contributor's agreement to submit a patch to the Plone core codebase? - -> We enthusiastically welcome patches, but we can't merge them until you sign and return a contributor's agreement. -> (Unless, in the judgement of the Plone Release Manager, the patch is so tiny as not to constitute a "creative work". -> See the [Policy for Contributor Agreements and Patches] for more detail on this policy.) - -Can I grant the Plone foundation a non-exclusive license to my contributions rather than an exclusive license, so that I can contribute the same code to other projects under different terms or use the contribution for other commercial endeavors? - -> Not under the current version of the contributors agreement. - -Does the Foundation control use of the Plone trademark? - -> Yes. -> In order to keep the trademark, the Foundation (or any trademark owner) must demonstrate that they have acted to protect it. - -Will Plone always be available under an OSI-approved/Open Source license? -Couldn't the Board change its mind about this? - -> Plone will always be available under an OSI-approved license; this is written into the language of the contributor agreement each developer and the foundation sign. - -Will Plone ever be available under a non-GPL license? - -> The current Plone approach states that companies can negotiate a non-GPL license. -> Thus, the Foundation might pursue a dual-licensing (GPL and non-GPL) scheme - -> but, at this time, the Board has not yet created any policies on this. -> This is an important question for the community, of course, and the Foundation intends to have this conversation in a transparent way. - -Why would anyone want a non-GPL Plone? - -> Two possible reasons: some companies are reluctant to do in-house modifications of framework-like systems (such as Plone) that are under the GPL, fearing that a clause in the GPL might force them to disclose their internal work - thus wanting to license it under (for example) a BSD-style license. -> Second, companies may wish to offer a commercial version of Plone, under a conventional shrink-wrap license, without the obligation to reveal source code or share changes. - -How much would a non-GPL version of Plone cost? - -> Would a small company be able to afford one? -> Neither the Foundation nor the Board have made any decisions about a non-GPL version, let alone about pricing. -> However, one of the Foundation's stated goals is to maintain a level playing field for Plone while trying to benefit all of the Plone commons. -> If a non-GPL version was available, and a large company bought it, -> added features to it, and sold it, wouldn't they be using our work without an obligation to give back? -> It's helpful to remember the core value open source provides: distributed development, maintenance, security checking, and support. -> Companies that build large features for Plone are **already** having to make decisions of whether to release their products under an open source license or not (since they could always release them as a Product, not as a modification to the Plone core). -> Despite this, though, many large and excellent contributions—such as Archetypes—have been made, and the Foundation hopes that companies will continue to do so. -> In any event, a company that purchases a non-GPL license (should such ever become available) is contributing financial resources to our community, which can be used to further develop, market, and protect the GPL version of Plone. - -- https://plone.org/foundation/contributors-agreement/agreement.pdf -- https://github.com/collective -- https://github.com/plone -- [Policy for Contributor Agreements and patches](https://plone.org/foundation/materials/foundation-resolutions/patch-policy-052011) diff --git a/coredev/culture.md b/coredev/culture.md deleted file mode 100644 index ff30aa2d8f..0000000000 --- a/coredev/culture.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone developer culture" - "property=og:description": "Plone developer culture" - "property=og:title": "Plone developer culture" - "keywords": "Plone, developer, culture" ---- - -```{todo} -All this can go, it's redundant -``` - -# Plone developer culture - -If you are going to contribute to Plone, we ask a couple things. -First, please join the [Plone forum](https://community.plone.org) and at minimum lurk around. -You will quickly see how people work and what kind of things are best suited for group discussion. -Second, please ask for help setting up your environment, in the forum. - -Most of our developers work there and you will get the best advice there. - -If you are actively committing code, always keep an eye on our [Jenkins CI](https://jenkins.plone.org/) to know if your recent commits have broken (or fixed!) the build. - -If you are in a timezone when things are not very active, please post to the forum or grab a drink and wait for people to wake up. - -**When in doubt, please ask** - -The code base is very complicated and everyone is vested in the right thing happening. -Despite the occasional grouch here and there, most Plone developers will go out of their way to get you on the right path. diff --git a/coredev/documentation.md b/coredev/documentation.md deleted file mode 100644 index bebf84e090..0000000000 --- a/coredev/documentation.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -myst: - html_meta: - "description": "Writing documentation of Plone" - "property=og:description": "Writing documentation of Plone" - "property=og:title": "Writing documentation of Plone" - "keywords": "documentation, Plone" ---- -```{todo} -shorten & update -``` - -# Writing documentation - -For general guidance for contributing documentation, see {doc}`contributing/index`. - -For documentation authors, see {doc}`contributing/authors`. - - -## Documentation of Plone - -The comprehensive resource for Plone documentation is https://6.docs.plone.org/. -The documentation repository is on [GitHub](https://github.com/plone/documentation). -Information for how to contribute to documentation can be found at {doc}`contributing/index`. - - -## Documenting a package - -At the very least, your package should include the following forms of documentation. - -### `README.md` - -The `README.md` is the first entry point for most people to your package. -It will be included on the PyPI page for your package, and on the front page of its GitHub repository. -It should be formatted using [GitHub flavored Markdown](https://github.github.com/gfm/) to get formatted properly by those systems. - -`README.md` should include: - -- A brief description of the package's purpose. -- Installation information (How do I get it working?) -- Compatibility information (what versions of Plone does it work with?) -- Links to other sources of documentation. -- Links to issue trackers, mailing lists, and other ways to get help. - - -### The manual (narrative documentation) - -The manual goes into further depth for people who want to know all about how to use the package. - -It includes topics like: - -- What are its features -- How to use them (in English—not doctests!) -- Information about architecture -- Common gotchas - -The manual should consider various audiences who may need different types of information: - -- End users who use Plone for content editing, but don't manage the site. -- Site administrators who install and configure the package. -- Integrators who need to extend the functionality of the package in code. -- System administrators who need to maintain the server running the software. - -Simple packages with limited functionality can get by with a single page of narrative documentation. -In this case, it's simplest to include it in an extended `README.md`. -Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching. - -If your project is moderately complex, you may want to set up your documentation with multiple pages. -The preferred way to do this is to add Sphinx to your project, and host your docs on readthedocs.org, so that it rebuilds the documentation whenever you push to GitHub. -If you do this, your `README.md` must link off site to the documentation. - - -### Reference or API documentation - -An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code). -It is meant for random access to remind the reader of how a particular class or method works, rather than for reading in its entirety. - -If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx. - - -### Changes or history - -```{todo} -Update for towncrier. -Probably purge all this content. -``` - -The changelog is a record of all the changes made to the package and who made them, with the most recent changes at the top. -This is maintained separately from the git commit history to give a chance for more user-friendly messages and to and record when releases were made. - -A changelog looks something like: - -```text -Changelog -========= - -1.0 (2012-03-25) ----------------- - -* Documented changelogs. - [davisagli] -``` - -See for a full example. - -If a change was related to a bug in the issue tracker, the changelog entry should include a link to that issue. - - -### Licenses - -Information about the open source license used for the package should be placed within the `docs` directory. - -For Plone core packages, this includes `LICENSE.md` and {file}`LICENSE.GPL`. diff --git a/coredev/getting-started-with-development.md b/coredev/getting-started-with-development.md deleted file mode 100644 index 003e6a7f28..0000000000 --- a/coredev/getting-started-with-development.md +++ /dev/null @@ -1,391 +0,0 @@ ---- -myst: - html_meta: - "description": "Getting started with Plone development" - "property=og:description": "Getting started with Plone development" - "property=og:title": "Getting started with Plone development" - "keywords": "Plone, development" ---- - -```{todo} -Needs updating to Plone6, but contains useful info -``` - -# Getting started with development - -This document assumes you want to run the current latest Plone source, fix a bug in Plone, or test an add-on in the context of the latest code, and will detail the full process. -For how to write Plone Improvement Proposals (PLIPs), read {doc}`plips`. - - -## Version support policy - -If you are triaging or fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule#91815aec-0513-40e0-a804-55ea787a8c68). - - -## Dependencies - -- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). -- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). -- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). - You can do this through the App Store or registering through the Apple Developer Program. -- [Pillow](https://pypi.org/project/Pillow/). -- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. - - -(setup-development-environment)= - -## Set up your development environment - -The first step in fixing a bug is getting this [buildout](https://github.com/plone/buildout.coredev) running. -We recommend fixing the bug on the latest branch, and then [backporting](https://en.wikipedia.org/wiki/Backporting) as necessary. -Dependent on the current development cycle, there may exist a future branch. -For example, `6.0` is the actively maintained stable branch. -[Some other branch] is the future, currently unstable, active development branch. -More information on switching release branches is described below. - -To set up a plone 6 development environment. - -```shell -cd ~/projects # or wherever you want to put things -git clone -b 6.0 https://github.com/plone/buildout.coredev ./plone6devel -cd ./plone6devel -./bootstrap.sh -``` - -If you run into issues in this process, please see {doc}`troubleshooting`. - -This will run for a long time if it is your first pull (approximately 20 minutes). -Once that is done pulling down eggs, you can start your new instance with: - -```shell -./bin/instance fg -``` - -or as a WSGI service with: - -```shell -./bin/wsgi -``` - -To login, the defaults are: - -- username: admin -- password: admin - - -## Switching branches - -If your bug is specific to one branch, or you think it should be backported, you can switch branches. -The first time you get a branch, you must do: - -```shell -git checkout -t origin/6.0 -``` - -This should set up a local 6.0 branch tracking the one on GitHub. -From then on you can just do: - -```shell -git checkout 6.0 -``` - -To see what branch you are currently on: - -```shell -git branch -``` - -The line with a `*` by it will indicate the branch on which you are currently working. - -```{important} -Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. -``` - - -## Jenkins and mr.roboto - -Plone has a continuous integration (CI) setup and follows CI rules. - -When you push a change to any Plone package, our testing/CI middleware `mr.roboto` starts running all the tests that are needed to make sure that you don't break anything. -For each Plone and Python version we run two jobs, one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are effected by your change. - -For more information you can read {doc}`Mr. Roboto workflow ` or our [Jenkins machine](https://jenkins.plone.org/). - -The CI system at `jenkins.plone.org` is a shared resource for Plone developers to notify them of regressions in Plone code. -Build breakages are a normal and expected part of the development process. -Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential practices that need to be followed in order to achieve a stable build: - -1. Don't check in on a broken build. Check Jenkins first. -2. Always run all commit tests locally before committing. -3. Wait for commit tests to pass before moving on. -4. Never go home on a broken build. -5. Always be prepared to revert to the previous revision. -6. Time-box fixing before reverting. -7. Don't comment out failing tests. -8. Take responsibility for all breakages that result from your changes. - -See {doc}`continous-integration` for more information. - -Since it can be burdensome to check this manually, install the tools locally to always see the current state of the Plone CI Server: - -- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). -- For macOS there is [CCMenu](http://ccmenu.org/). -- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). -- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). - -These tools were built to parse a specific file that CruiseControl, another CI tool, generated. -Jenkins generates this file too. -You can configure your notifier of choice with this url: `https://jenkins.plone.org/cc.xml` [which is a 404, LOL!] - - -## Check out packages to fix - -Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. -It can be a little daunting at first to find out which packages cause the bug in question, but just ask in https://community.plone.org/ if you need some help. -Once you know which packages you want, pull their source. - -You can get the source of the package with `mr.developer` and the checkout command, or you can go directly to editing {file}`checkouts.cfg`. -We recommend the latter but will describe both. -In the end, {file}`checkouts.cfg` must be configured, so you might as well start there. - -At the base of your buildout, open {file}`checkouts.cfg` and add your package if it's not already there: - -```cfg -auto-checkout = - # my modified packages - plone.app.caching - plone.caching - # others - ... -``` - -Then rerun buildout to get the source packages: - -```shell -./bin/buildout -``` - -Alternatively, we can manage checkouts from the command line, by using `mr.developer`'s `bin/develop` command to get the latest source. -For example, if the issue is in `plone.app.caching` and `plone.caching`: - -```shell -./bin/develop co plone.app.caching -./bin/develop co plone.caching -./bin/buildout -``` - -Don't forget to rerun buildout! -In both methods, `mr.developer` will download the source from GitHub (or otherwise) and put the package in the {file}`src/` directory. -You can repeat this process with as many or as few packages as you need. -For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. - - -## Testing Locally - -To run a test for the specific module you modify: - -```shell -./bin/test -m plone.app.caching -``` - -These should all run without error. -Please don't check in anything that doesn't succeed! -Now write a test case for the bug you are fixing, and make sure everything is running as it should. - -After the module level tests run with your change, please make sure other modules aren't affected by the change by running the full suite, including robot-tests (remove the `--all` to run without robot tests): - -```shell -./bin/test --all -``` - -```{note} -Tests take a long time to run. -Once you become a master of bugfixes, -you may just let jenkins do this part for you. -More on that below. -``` - - -## Updating `CHANGES.rst` and `checkouts.cfg` - -Once all the tests are running locally on your machine, you are **ALMOST** ready to commit the changes. -You must perform a couple housekeeping chores before moving on. - -First, edit {file}`CHANGES.rst` (or {file}`CHANGES.txt`, or {file}`HISTORY.txt`) in each package you have modified and add a summary of the change. -This change note will be collated for the next Plone release and is important for integrators and developers to be able to see what they will get if they upgrade. -New changelog entries should be added at the very top of {file}`CHANGES.rst`. -Some packages already switched to use [towncrier](https://pypi.org/project/towncrier/). -If this is the case you'll find a note at the top of the `CHANGES.rst` file. - -Most importantly, if you didn't do it earlier, edit the file {file}`checkouts.cfg` in the buildout directory, and add your changes package to the `auto-checkout` list. -This lets the release manager know that the package has been updated, so that when the next release of Plone is cut, a new egg will be released, and Plone will need to pin to the next version of that package. -In other words, this is how your fix becomes an egg! - -Note that there is a section separator called "# Test Fixes Only". -Make sure your egg is above that line, else your egg probably won't get made very quickly. -This just tells the release manager that any eggs below this line have tests that are updated, but no code changes. - -Modifying the file {file}`checkouts.cfg` also triggers the buildbot, [jenkins](https://jenkins.plone.org/), to pull in the egg and run all the tests against the changes you just made. -Not that you would ever skip running all tests. - -If your bug is in more than one release, for example 5.2 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg`. - - -## Commits and pull requests - -Review the following checklist: - -- Did you fix the original bug? -- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? -- Did you remove any extra code and lingering pdbs? -- Did you write a test case for that bug? -- DO all test cases for the modules and Plone pass? -- Did you update {file}`CHANGES.rst` in each packages you touched? -- Did you add your changed packages to {file}`checkouts.cfg`? - -If you answered *YES* to all of these questions, then you are ready to push your changes! -A couple quick reminders: - -- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. - Otherwise, please create a `pull request` (more on that below). -- Please try to make one change per commit. - If you are fixing three bugs, make three commits. - That way, it is easier to see what was done when, and easier to roll back any changes if necessary. - If you want to make large changes cleaning up whitespace or renaming variables, it is especially important to do so in a separate commit for this reason. -- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! - If you commit something REALLY sketchy, they will politely contact you, most likely after immediately reverting changes. - There are no official people assigned to this so if you are especially nervous, ask in https://community.plone.org/. - - -## Commit to `Products.CMFPlone` - -If you are working a bug fix on `Products.CMFPlone`, there are a couple other things to take notice of. -First and foremost, you'll see that there are several branches. -At the time of writing this document, there are branches for 4.2.x, 4.3.x and master, which is the implied 5.0. -This may change faster than this documentation, so check the branch dropdown on GitHub. - -If the fix is only for one version, make sure to get that branch. -However, chances are the bug is in multiple branches. - -Let's say the bug starts in 4.1. -Pull the 4.1 branch and fix and commit there with tests. - -If your fix only involved a single commit, you can use git's `cherry-pick` command to apply the same commit to a different branch. - -First check out the branch: - -```shell -git checkout 4.2 -``` - -And then cherry-pick the commit (you can get the SHA hash from git log): - -```shell -git cherry-pick b6ff4309 -``` - -There may be conflicts. -If so, resolve them, then follow the directions git gives you to complete the cherry-pick. - -If your fix involved multiple commits, cherry-picking them one by one can get tedious. -In this case, things are easiest if you did your fix in a separate feature branch. - -In that scenario, you first merge the feature branch to the 4.1 branch: - -```shell -git checkout 4.1 -git merge my-awesome-feature -``` - -Then return to the feature branch, and make a branch for rebasing it onto the 4.2 branch: - -```shell -git checkout my-awesome-feature -git checkout -b my-awesome-feature-4.2 -git rebase ef978a --onto 4.2 -``` - -(`ef978a` happens to be the last commit in the feature branch's history before it was branched off of 4.1. -You can look at `git log` to find this.) - -At this point, the feature branch's history has been updated, but it hasn't actually been merged to 4.2 yet. -This lets you deal with resolving conflicts before you actually merge it to the 4.2 release branch. -Let's do that now: - -```shell -git checkout 4.2 -git merge my-awesome-feature-4.2 -``` - -### Branches and forks and direct commits - oh my! - -```{note} -This section needs a rewrite. -Meanwhile we do not allow direct commits, except in very rare cases. -``` - -Plone used to be in an svn repository, so everyone is familiar and accustomed to committing directly to the branches. -After the migration to GitHub, the community decided to maintain this spirit. -If you have signed the [contributor agreement](https://plone.org/foundation/contributors-agreement), you can commit directly to the branch. -For Plone, this would be the version branch, whereas for most other packages this would be `main`. - -HOWEVER, there are a few situations where a branch is appropriate. -If you: - -- are just getting started -- are not sure about your changes -- want feedback or code review -- are implementing a non-trivial change - -then you should create a branch of whatever packages you are using, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. -Everything about this process would be the same except you need to work on a branch. -Take the `plone.app.caching` example. -After checking it out with `mr.developer`, create your own branch with: - -```shell -cd src/plone.app.caching -git checkout -b my_descriptive_branch_name -``` - -```{note} -Branching or forking is your choice. -I prefer branching, and I'm writing the docs so this uses the branch method. -If you branch, it helps us because we *know* that you have committer rights. -Either way it's your call. -``` - -Proceed as normal. -When you are ready to push your fix, push to a remote branch with: - -```shell -git push origin my_descriptive_branch_name -``` - -This will make a remote branch in GitHub. -Navigate to this branch in the GitHub user interface, and on the top right, there will be a button that says {guilabel}`Pull Request`. -This will turn your request into a pull request on the main branch. -There are people who look once a week or more for pending pull requests and will confirm whether or not it's a good fix, and give you feedback where necessary. -The reviewers are informal and very nice, so don't worry. -They are there to help! -If you want immediate feedback, visit https://community.plone.org/ with the pull request link and ask for a review. - -```{note} -You still need to update the file {file}`checkouts.cfg` in the correct branches of `buildout.coredev`! -``` - - -## Finalize issues - -If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. -We don't have integration with GitHub yet so it's a nice way to track changes. -It also lets the reporter know that you care. -If the bug is really bad, consider pinging the release manager and asking them to make a release. - - -## FAQ - -How do I know when my package got made? -: You can follow the project on GitHub, and watch its [timeline](https://github.com/orgs/plone/dashboard). - You can also check the {file}`CHANGES.rst` of every plone release for a comprehensive list of all changes, and validate that yours is present. diff --git a/coredev/git.md b/coredev/git.md deleted file mode 100644 index 10696f8d36..0000000000 --- a/coredev/git.md +++ /dev/null @@ -1,640 +0,0 @@ ---- -myst: - html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" ---- - -```{todo} -All this can go, it's redundant -``` - -# Working with Git and GitHub - -## The Plone Git workflow and branching model - -Our repository on GitHub has the following layout: - -- **feature branches**: - All development for new features must be done in dedicated branches, normally one branch per feature. -- **main** or **master** **branch**: - when features get completed they are merged into the master branch; bugfixes are commited directly on the master branch, -- **tags**: - whenever we create a new release, we tag the repository so we can later retrace our steps, or rerelease versions. - - -## Git basics - -Some introductory definitions and concepts, if you are already familiar enough with Git, head to next section: {ref}`general-guidelines-label`. - - -### Mental working model - -With Git (as well as all modern [DVCS](http://en.wikipedia.org/wiki/Distributed_revision_control)), distributing changes to others is a two steps process (contrary to traditional VCS like `svn`). - -This way what on svn is a single `svn ci` in Git is two commands: `git commit` and `git push`. - -This may seem to be a drawback, but instead it's a feature. - -**You are working locally until you decide to push your changes.** - -Not a single commit anymore, but a series of them, meaning that all those fears, concerns, doubts are taken away! - -You can freely fix/change/remove/rework/update/... your commits afterwards. - -Push your changes whenever you are sure they are what you, and others, expect them to be. - - -### Concepts - -In Git there are: - -commits - -: A patch made out of changes (additions, removals) on files tracked by Git. - -branches - -: Series of commits that have a name. - -tags - -: A name attached to a single commit. - -`HEAD` - -: A pointer that always tells you where you are (extremely useful when doing some operations). - -The index - -: A temporal staging storage with changes on files that are pending to be added to a commit. - If your Git output is colored, green filenames are those in the index. - -Working tree - -: Your current modified files. - This is the only place where you can loose your changes. - If your Git output is colored, red filenames are those in the working tree. - -Stash - -: Temporal storage for changes, again, extremely useful in some scenarios, see further below for examples. - -### Branches - -Another great feature of DVCS is cheap branching, i.e. branching in Git is effortless and really useful. -As it's no longer too much effort to branch, there is no need to always work on the master branch. - -A developer can branch easily for each fix/feature. - -Branches allow you to tinker with your changes while keeping the master branch clean. - -Not only that, it also allows you to keep modifying your changes until you and your peers are fine with them. - -Further documentation: -[Introduction to branching](http://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell). - -### Commands - -Some of the most useful/common commands (note that most of them have switches that enhance/*completely twist* their functionality): - -Just append `--help` on all of them to get their full definitions and options, -i.e. `git add --help`. - -clone - -: Download a repository from a given remote URL. - -add - -: Add the given files to the index. - - ```{note} - **pro tip**: once a file is add via `git add` your changes will never be lost! - As long as you don't remove the `.git` folder, even if you remove the file you just added, the changes you made before doing `git add` are still there ready to be recovered at any time! - ``` - -status - -: Get an overview of the repository status. - - If there are files on the index, or files not tracked by Git, or the status of your local branch with regards to the remote, etc. - -diff - -: See the current changes made to the files already tracked by Git. - - ```note} - Fear not, if you used `git add SOME_FILE` and then `git diff` doesn't output anything you haven't lost your changes! - - Just try `git diff --cached`. - Now you know how to see the working tree changes (`git diff`) and index changes (`git diff --cached`). - ``` - -commit - -: Create/record changes to the repository (locally only, nothing is sent over the wire). - -push - -: Send your changes, - either commits or a complete new branch, - to the configured remote repository. - -show - -: Display the given commit(s) details. - -log - -: Shows the repository history. - Sorted by date (last commit at the top), - and like all other commands, - extremely versatile with all its switches. - - See further below for an example of a powerful combination of switches. - -branch - -: Create a branch. - -fetch - -: Download changes from the remote repository. - - **Without** changing the current `HEAD` (see rebase and pull commands). - -pull - -: Fetch and integrate changes from remote repository. - - Internally that means to do a `git fetch` plus either `git merge` or `git rebase`. - - :::{note} - Used careless most probably adds extra superfluous commits. - See further down. - ::: - -merge - -: Join two, - or more, - branches together. - -rebase - -: Forward-port your current local commits (or branch) to be based on top of another commit. - - An image is worth 1000 words: - -checkout - -: Change to the given branch or get the given file to its latest committed version. - - :::{note} - If Git is criticized for being complex, - this command is one of the main sources of complains. - - You can compare it with `svn switch` if you happen to know it. - - Fear not though, - two main use cases are: - change branches and reset a file to its last committed version. - Still, - the syntax for both cases is really simple. - ::: - -cherry-pick - -: Apply a commit(s) to the current working branch. - -stash - -: Use a temporal storage to save/restore current changes still not meant to be used on a commit. - - :::{note} - Seems a bit not so useful on a first look, - but it is indeed. - - Think about this scenario: - you are working on your branch coding away. - All of the sudden you notice a small fix that should be done directly on master. - Thanks to `git stash` you can save your changes quickly and safely, - move to master branch, - do the quick fix, - commit and push it, - move back to your branch and `git stash pop` to recover your changes and continue hacking away. - ::: - -reflog - -: When things go bad you will **love** this command. - - It effectively shows you a histogram of what happened on the repository, - allowing you to rollback you repository to a previous stage. - - Extremely useful once a bad interactive rebase has happened. - -(general-guidelines-label)= - -## General guidelines - -### Pulling code - -Let's compare this two histories: - -``` -* 3333333 (HEAD, master) Merge branch 'feature-branch' into master -|\ -| * 2222222 (feature-branch) Last changes on feature-branch -| * 1111111 Merge branch 'master' into feature-branch -| |\ -| * | 0000000 More changes on feature branch -| * | fffffff Merge branch 'master' into feature-branch -| |\ \ -* | | | eeeeeee master keeps rocking -| |_|/ -|/| | -* | | ddddddd master goes and goes -| |/ -|/| -* | ccccccc master evolves -| * bbbbbbb First commit on feature-branch -|/ -* aaaaaaa commit on master # this is where feature-branch was created -``` - -With: - -``` -* 3333333 (HEAD, master) Merge branch 'feature-branch' into master -|\ -| * 2222221 (feature-branch) Last changes on feature-branch -| * 0000001 More changes on feature branch -| * bbbbbb1 First commit on feature-branch -|/ -* eeeeeee master keeps rocking -* ddddddd master goes and goes -* ccccccc master evolves -* aaaaaaa commit on master -``` - -What do we see above? Actually and contrary to what it seems, -exactly the same **result** -(as how the files and its content look like on commit `333333`). - -The second version is far more easy to understand what happened and removes two superfluous commits -(the two partial merges with master (`fffffff` and `1111111`). - -This happens if you have not properly configured `git pull`. -By default it does a `merge` meaning that an extra commit is always added, -tangling the history and making this more complex when looking back for what happened there. - -#### How to solve it? - -*ALWAYS* do a {command}`git pull --rebase` when fetching new code, -configure Git to do always so with: - -``` -git config branch.autosetuprebase always # add the --global switch to make it default everywhere -``` - -This way you do not introduce new extra commits and the Git history is kept as simple as possible. - -This is especially important when trying to understand why some changes were made, -or who did actually change that line, -etc. - -A couple of further explanations: - - - - -Search for `git merge vs rebase`, you will find plenty of literature. - -### Reviewing your changes - -After hacking for some minutes/hours/days you are finished and about to commit your changes, -great! - -*BUT*, -please, -do so with {command}`git add --patch`. - -The `--patch` (also `-p`) switch allows you to select which hunks you want to add on a commit. - -This is not only great to split changes into different commits, -but is also the time when you actually **review** your code before anyone else sees it. - -This is the time when you spot typos, pep8 errors, misaligned code, lack of docstrings in methods, -that a permission is not defined on Generic Setup, that an upgrade should be needed... - -Remember that the first code review is the one you do on your own. -Some inspiration/better phrasing: - - -And please, do remember the gold metric about reviewing code: - - -#### One commit does one thing - -Repeat with me: *One commit does one thing*. Period. - -When someone else needs to review your code, most probably she will give up or just skim over your code -if there are too many (unrelated) changes. - -Reviewing commits with +20 files doing all sorts of changes on them (maybe even unrelated) -is no fun and adds complexity and [cognitive load](http://en.wikipedia.org/wiki/Cognitive_load). - -Something that should mostly be a verification of a checklist like: - -- the browser view is registered on ZCML? - -- is there an interface for that form? - -- the pt and py are there? - -- ... - -Turns instead into a list of questions: - -- why is this interface renamed here if it has nothing to do with this adapter? -- all this removal of deprecated code while adding new features just mixes the diff, - am I missing something? -- *others* - -If you can not express what has been changed within 50 characters (suggested length of a commit message subject), -or you say it like "it does XXX and YYY", you most probably need to split that commit into, at least, -two or more commits. - -That doesn't mean that a +20 files or +100 lines of code changes are bad per se, you may be doing -a simple refactoring across lots of files, that's fine and good actually. - -As long as a commit is just and only about a specific purpose, and not a mixed selection of the following: - -- refactoring code -- moving things around -- fixing some bugs while at it -- adding some docs -- a new cool feature -- fixing typos on documentation -- pep8 fixes - -It is absolutely fine to refactor. - -And this is actually to help both your present self and your +5 years from now that will have to refactor that code of yours, -and maybe is struggling to understand what was going on there. - -Following this advice will: - -- keep things simple where there's no gain in adding complexity -- make your changes easy to be reviewed -- make later on lookups on those changes easy to follow - -### Making commits - -For commit messages see: {ref}`git_commit_message_style_guide`. - -#### Adding references to issues - -Always add the full URL to the issue/pull request you are fixing/referring to. - -Maybe within the Git repository it makes sense, but as soon as you are outside of it, it will not. - -Take into account mr.roboto automatic commits to buildout.coredev for example, if your commit message goes like *Fix for #33*, -which issue/pull request is that fixing? - -The one in buildout.coredev itself? On another issue tracker? Somewhere else? - -It would be far better if the commit goes instead like: - -``` -Brief description - -Further explanation. - -Fixes: https://github.com/plone/plone.app.discussion/issue/999 -``` - -#### Bad examples - -Some bad examples of commit messages: - - -Commit messages goes like *"Make note about how this interface is now for BBB only"*. - -Question: if it's BBB only, where is the new place to look for that interface now? - -The problem is that, in this case Martin, wrote that in 2009, so most probably once a refactor of that package -is done later on 2015, Martin is no longer around, and if he was, most probably he would not remember something from +6 years ago. - -Ask yourself a question: - -If someone comes to you asking details about a random commit done by you +5 years ago, what will you reply? - -Try that, get one project that you worked 5 years ago, get a random commit and: - -See if, just by reading the commit message, you are given enough information of what changes have been made, -when comparing the commit message and the actual code. -Does the commit message match the code changed? - -### Before pushing commits - -Code is reviewed, spread into nice isolated commits, descriptive enough commit messages are written, *what's left?* - -A final overview of what you are about to push. - -To do so, you can get an idea with the following Git alias (to be added on your `~/.gitconfig`): - -``` -[alias] - fulllog = log --graph --decorate --pretty=oneline --abbrev-commit --all -``` - -Now run {command}`git fulllog` on your Git repository, you will see a nice graph showing you the current situation. - -Maybe it makes you realize that commits need to be reordered, commit messages could get some improvements, -that you forgot to add a reference to an issue, ... - -## Pull requests - -Some specific tips and best practices for pull requests. - -### Always rebase - -Always rebase on top of the branch you want your changes to be merged before sending a pull request, -and as your pull request is still pending to be merged and the master branch evolves, keep rebasing it. - -To do so: - -``` -git checkout -git rebase master # or the branch you are targeting to integrate your changes to -# done! -# or if there are conflicts, -# fix them and follow instructions from git itself -``` - -The principle is, if you do merges with master, you are actually spreading your pull request into more commits, -and at the end making it more difficult to track what was changed. - -On top of that, the commit history is more complex to follow. - -See the history example above: {ref}`general-guidelines-label`. - -Unfortunately the flat view from GitHub prevents us from seeing that, -which is a shame. - -### One line one commit - -On a series of commits make sure the same code line is not changed twice, -the worst thing you can do to the one reviewing your changes, -is to make him/her spend time reviewing some code changes that one the next commit are changed again to do something else. - -It will not only make your commits smaller, but it will also make it easy to do atomic commits. - -### No cleanup commits please - -*On the context of a pull request* - -Ask yourself: What relation does a cleanup commit, say pep8 fixes or other code analysis fixes, -have with your pull request? - -Couldn't that pep8 fixes commit or small refactoring go straight into master branch? - -Or even if you send a pull request for it, chances are that it will be merged right away. -As long as it is a cleanup commit, there's not much to argue with it. - -The same goes with commits that improve or actually fix previous commits (within the same pull request). -A series of commits like this: - -``` -* 11ba28c Last fix, finally -* 11ba28c Fix tests, again -* 11ba28c Fix tests -* 11ba28c Do something fancy -* 11ba28c Failing test, we are doing TDD right? -``` - -Only tells you that the author did not take care at all about the one who will review it, -and specially about the person that in +5 years will try to understand that test. -Specially because now the test is not only spread between 4 commits, but most probably during those 5 years -it has already been refactored, maybe a {command}`git blame` will report that within that test method, -there are +5 related current commits to check, not nice right? - -#### Squashing commits - -To fix the previous example, run the following command: - -``` -git rebase ---interactive # which mostly is usually master -``` - -This allows you to rewrite the story of your branch. -See a more [elaborate description with examples](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase-i/). - -:::{note} -Be careful on not to run that on master itself! -Please take your time to really understand it. - -It's a really powerful tool, -and as [Stan Lee says](http://en.wikiquote.org/wiki/Stan_Lee), -it comes with great responsibility. -::: - -To actually make it easier you can do commits like this: - -``` -git commit --fixup HASH -``` - -Where `HASH` is the commit hash you want the changes you are about to commit be merged with. - -This way, when running {command}`git rebase --interactive`, Git will already reorder the commits as you already want. - -### No side changes - -That's an extension to the previous point. - -Keeping pull requests simple and to the point, without changes not related to the pull request itself, -will make your changes easier to understand and easier to follow. - -Again this applies: - - -### The review-change-push-review cycle - -After you have made a pull request, -you should ask for a review via the GitHub interface. - -After the review you will frequently have to do some changes of your PR, -perhaps add a missing changelog entry, and so on. - -When the changes are done, rebase your branch again -and squash any fixup-commits, all as described above. - -Finally you should force push your feature branch to GitHub. -Only force push on your own feature branches! -Never on branches shared with other people. - -After the update of your branch, -the GitHub PR interface will pick up the changes, -ready for returning to the reviewer, -and hopefully get a final go for the merge. - -## Recipes - -Assorted list of tips and tricks. - -### Change branches with uncommitted changes - -**Situation:** you are working on a pull request and while working on it founds that some cleanups are needed, -how to proceed forward? - -**Solution:** `git stash` or `git commit --amend -m"TMP"`. - -The basic idea here is: store your current changes safely (either on a Git stash commit or directly on a commit on the branch, -whichever you prefer), move to the canonical branch (`master` usually), do the fixes/cleanups/refactorings there, -commit those changes, rebase your branch on top of the changes you made, hack away. - -Command line version: - -``` -git stash # or git commit --amend -m"TMP" -git checkout master # or whatever happens to be the canonical branch name (i.e. 5.0 on buildout.coredev) -# do the cleanups && push them -git checkout your-branch # get back to your branch -git rebase master # again the canonical branch where you made the changes -git stash pop # or git reset HEAD^ if you did a git commit --amend -m"TMP" -# if needed, fix the conflicts, with patience and practise that's a piece of cake once you are used to -``` - -### Git visual applications - -Not everyone is a fan of the command line, for them there is a list of GUI clients on the official Git website: - - - -### Enhanced Git prompt - -Do one (or more) of the following: - -- -- -- - -### Git dotfiles - -Plone developers have dotfiles similar to these: -. - -## Learn more - -What's here is just the tip of the iceberg, there's plenty of Git knowledge on the web. - -A few good further resources are listed here (contributions welcome): - -- official online Git book: [Pro Git](http://git-scm.com/book/en/v2) -- PyCon 2015 talk: [Advanced Git by David Baumgold](https://www.youtube.com/watch?v=4EOZvow1mk4) diff --git a/coredev/guidelines.md b/coredev/guidelines.md deleted file mode 100644 index 331c25e346..0000000000 --- a/coredev/guidelines.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -myst: - html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" ---- - -```{todo} -All this can go, it's redundant. -IMPORTANT: it does need a rewrite on 6.docs.plone.org as there are many packages in the wild that link to it. -``` - -% Note: this page is linked to from CONTRIBUTING.rst in all packages. Keep it short! - -# Guidelines for contributing to Plone Core - -You probably came here by clicking one of the 'guidelines for contributing' links on GitHub. -You probably have an issue to report or you want to create a pull request. -Thanks a lot! -Let's bring you up to speed with the minimum you need to know to start contributing. - -## Create an issue - -- If you know the issue is for a specific package, you can add an issue there. - When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues). - -- Please specify a few things: - - - What steps reproduce the problem? - - What do you expect when you do that? - - What happens instead? - - Which Plone version are you using? - -- If it is a visual issue, can you add a screen shot? - -- If there is an error in the Site Setup error log, please include it. - Especially a traceback is helpful. - Click on the 'Display traceback as text' link if you see it in the error log. - - -## Create a pull request - -- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. - This means that we can NOT accept pull requests from you unless this is done, so please don't put the code reviewers at risk and do it anyways. -- Add a changelog entry as file in the news directory. - For helpful instructions, please see: -- For new features, an addition to README.rst is probably needed. - A package may include other documentation that needs updating. -- All text that can be shown in a browser must be translatable. - Please mark all such strings as translatable. -- Be nice and use code quality checkers like flake8 and jshint. -- See if you can use git to squash multiple commits into one where this makes sense. - If you are not comfortable with git, never mind. -- If after reading this you become hesitant: don't worry. - You can always create a pull request, mark it as WIP (work in progress), and improve the above points later. diff --git a/coredev/index.md b/coredev/index.md deleted file mode 100644 index 41192a3579..0000000000 --- a/coredev/index.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -myst: - html_meta: - "description": "Development in Plone" - "property=og:description": "Development in Plone" - "property=og:title": "Development in Plone" - "keywords": "Developing, Plone, Contributing" ---- - -```{todo} -Most of this can go -``` - -# Development in Plone - -This part describes the process of development in Plone. -It is primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). - - -## Plone Contributor Agreement - -You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). - -We can **NOT** accept pull requests from you until you have signed and returned the Contributor Agreement, and been approved. -Please don't put the code reviewers at risk by ignoring this requirement. - - -## Contents - -```{toctree} -:maxdepth: 2 - -guidelines -agreement -culture -getting-started-with-development -documentation -plips -issues -release -git -package-dependencies -``` - - -## Additional material - -These are some documents used as reference for this documentation. - -```{toctree} -:maxdepth: 1 - -contributors-agreement-explained -continous-integration -roboto -mrdeveloper -plip-review -``` - -```{todo} -The style guides are ancient and need to be overhauled. -``` - -Documenation's style is guided by Vale and the Microsoft Style Guide. -See [Contributing to Documentation](https://6.docs.plone.org/contributing/index.html). - -Our coding style guides are located at the [Plone Style Guide](https://5.docs.plone.org/develop/styleguide/index.html section. diff --git a/coredev/mrdeveloper.md b/coredev/mrdeveloper.md deleted file mode 100644 index f0480b0c1b..0000000000 --- a/coredev/mrdeveloper.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -myst: - html_meta: - "description": "mr.developer" - "property=og:description": "mr.developer" - "property=og:title": "mr.developer" - "keywords": "mr.developer" ---- - -```{todo} -Review, but keep -``` - -# `mr.developer` - -This buildout uses `mr.developer` to manage package development. -See https://pypi.org/project/mr.developer/ for more information, or run `bin/develop help` for a list of available commands. - -The most common workflow to get all the latest updates is: - -```shell -git pull -bin/develop rb -``` - -This will get you the latest `coredev` configuration, checkout and update all packages via git and Subversion in src, and run buildout to configure the whole thing. - -From time to time you can check if some old cruft has accumulated: - -```shell -bin/develop st -``` - -If this prints any lines with a question mark in front, you can cleanup by: - -```shell -bin/develop purge -``` - -This will remove packages from {file}`src/` which are no longer needed, as they have been replaced by proper egg releases of these packages. diff --git a/coredev/packages-dependencies.md b/coredev/packages-dependencies.md deleted file mode 100644 index 8f95a4f704..0000000000 --- a/coredev/packages-dependencies.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -myst: - html_meta: - "description": "This chapter describes the architecture of Plone's packages and dependencies." - "property=og:description": "This chapter describes the architecture of Plone's packages and dependencies." - "property=og:title": "Architecture: packages and dependecies" - "keywords": "Architecture, packages, dependecies, Plone" ---- - -```{todo} -Needs grammar/style check, and re-do the ASCII art as Mermaid diagram for added clarity and visuals -``` - -# Architecture: packages and dependecies - -This chapter describes the architecture of Plone's packages and dependencies. - - -## Motivation - -In the past, lots of indirections were introduced in Plone's packages and dependecies. -Our goal in the long run is to untangle them and get a direct dependency graph. -This document shows the current state as an orientation. - - -## Overview - -There are multiple level of dependencies: - -- package level (`setup.py`/`setup.cfg`/`pyproject.toml`) -- Python level (imports) -- ZCML level (includes) -- testing (need for layers, such as functional testing) - -We do not have any circular dependencies at the package level anymore. -This was solved already. - -Nevertheless we have indirection on all other levels. -Since Plone consists of a lot of packages, it is complex to untangle those. - - -## Mental model - -A base mental model for how Plone is organized in Plone 6 since alpha 4 is shown in the following diagram: - -``` -┌────────────────────────────┐ -│ "Plone" | -| The Integration of both | -| distributions in one | -| Release | -├────────────────────────────┤ -| Distributions: | -| - plone.volto | -| - plone.classicui | -├────────────────────────────┤ -│ Core-Addons │ -│ - plone.distribution │ -│ - plone.app.exportimport │ -│ - plone.app.discussion │ -│ - plone.app.multilingual │ -│ - plone.app.caching │ -│ - plone.app.iterate │ -│ - plone.app.update │ -│ │ -├────────────────────────────┤ -│ Core-APIs │ -│ - plone.restapi │ -│ - plone.api │ -├────────────────────────────┤ -│ │ -│ Products.CMFPlone │ -│ │ -├────────────────────────────┤ -│ │ -│ The space between (core ) │ -│ │ -│ - most of plone.app.* │ -│ - but also some other │ -│ │ -├────────────────────────────┤ -│ │ -│ plone.base │ -│ │ -├────────────────────────────┤ -│ │ -│ The Foundations │ -│ │ -│ - Zope │ -│ - CMFCore │ -│ - PAS/PlonePAS │ -│ - plone.registry │ -│ - plone.dexterity │ -│ - plone.behavior │ -│ - plone.rest │ -│ - .... │ -│ │ -└────────────────────────────┘ -``` - -As a rough model we have two packages as dividing lines: - -1. `Products.CMFPlone` -2. `plone.base` - - -## Packages in detail - -If we look deeper into those, we have more sub-dividers, but first group all into the three groups: - -Then, based on the 6.0.0.a4 release, these are the packages: - - -### Above `Products.CMFPlone` - -- Plone -- plone.api -- plone.app.iterate -- plone.app.upgrade -- plone.restapi -- plone.volto -- Products.CMFPlacefulWorkflow - - -### Between `Products.CMFPlone` and `plone.base` - -- collective.monkeypatcher -- plone.app.caching -- plone.app.content -- plone.app.contentlisting -- plone.app.contentmenu -- plone.app.contentrules -- plone.app.contenttypes -- plone.app.customerize -- plone.app.dexterity -- plone.app.discussion -- plone.app.event -- plone.app.i18n -- plone.app.intid -- plone.app.layout -- plone.app.linkintegrity -- plone.app.locales -- plone.app.lockingbehavior -- plone.app.multilingual -- plone.app.portlets -- plone.app.querystring -- plone.app.redirector -- plone.app.registry -- plone.app.relationfield -- plone.app.textfield -- plone.app.theming -- plone.app.users -- plone.app.uuid -- plone.app.versioningbehavior -- plone.app.viewletmanager -- plone.app.vocabularies -- plone.app.widgets -- plone.app.workflow -- plone.app.z3cform -- plone.browserlayer -- plone.cachepurging -- plone.contentrules -- plone.formwidget.namedfile -- plone.formwidget.recurrence -- plone.i18n -- plone.namedfile -- plone.outputfilters -- plone.portlet.collection -- plone.portlet.static -- plone.portlets -- plone.protect -- plone.resourceeditor -- plone.rfc822 -- plone.schemaeditor -- plone.session -- plone.staticresources -- plone.stringinterp -- plone.theme -- plonetheme.barceloneta -- Products.isurlinportal - - -### The foundation below `plone.base` - - -#### Plone world - -- borg.localrole -- plone.alterego -- plone.autoform -- plone.autoinclude -- plone.batching -- plone.behavior -- plone.caching -- plone.dexterity -- plone.event -- plone.folder -- plone.indexer -- plone.intelligenttext -- plone.keyring -- plone.locking -- plone.memoize -- plone.registry -- plone.resource -- plone.rest -- plone.scale -- plone.schema -- plone.subrequest -- plone.supermodel -- plone.transformchain -- plone.uuid -- plone.z3cform -- Products.DateRecurringIndex -- Products.ExtendedPathIndex -- Products.MimetypesRegistry -- Products.PlonePAS -- Products.PortalTransforms -- Products.statusmessages - - -#### Zope ecosystem - -- Chameleon -- diazo -- five.customerize -- five.intid -- five.localsitemanager -- icalendar -- Products.CMFCore -- Products.CMFDiffTool -- Products.CMFDynamicViewFTI -- Products.CMFEditions -- Products.CMFUid -- Products.DCWorkflow -- Products.ExternalMethod -- Products.GenericSetup -- Products.MailHost -- Products.PluggableAuthService -- Products.PluginRegistry -- Products.PythonScripts -- Products.Sessions -- Products.SiteErrorLog -- Products.StandardCacheManagers -- Products.ZopeVersionControl -- repoze.xmliter -- webresource -- z3c.caching -- z3c.form -- z3c.formwidget.query -- z3c.objpath -- z3c.pt -- z3c.relationfield -- z3c.zcmlhook -- zc.recipe.egg -- zc.relation -- zodbverify -- zope.copy -- zope.intid -- zope.keyreference - - -#### Zope core - -- AccessControl -- Acquisition -- AuthEncoding -- beautifulsoup4 -- BTrees -- DateTime -- DocumentTemplate -- ExtensionClass -- Missing -- MultiMapping -- Persistence -- persistent -- Products.BTreeFolder2 -- Products.ZCatalog -- Record -- RestrictedPython -- transaction -- zc.lockfile -- ZConfig -- zdaemon -- ZEO -- zExceptions -- ZODB -- ZODB3 -- zodbpickle -- Zope -- zope.annotation -- zope.app.locales -- zope.browser -- zope.browsermenu -- zope.browserpage -- zope.browserresource -- zope.cachedescriptors -- zope.component -- zope.componentvocabulary -- zope.configuration -- zope.container -- zope.contentprovider -- zope.contenttype -- zope.datetime -- zope.deferredimport -- zope.deprecation -- zope.dottedname -- zope.event -- zope.exceptions -- zope.filerepresentation -- zope.globalrequest -- zope.hookable -- zope.i18n -- zope.i18nmessageid -- zope.interface -- zope.lifecycleevent -- zope.location -- zope.pagetemplate -- zope.processlifetime -- zope.proxy -- zope.ptresource -- zope.publisher -- zope.ramcache -- zope.schema -- zope.security -- zope.sendmail -- zope.sequencesort -- zope.site -- zope.size -- zope.structuredtext -- zope.tal -- zope.tales -- zope.testbrowser -- zope.testing -- zope.traversing -- zope.viewlet -- Zope2 - - -#### Libraries - -- attrs -- cffi -- cssselect -- decorator -- docutils -- feedparser -- future -- importlib_metadata -- jsonschema -- Markdown -- multipart -- Paste -- PasteDeploy -- piexif -- Pillow -- pycparser -- PyJWT -- pyrsistent -- python_dotenv -- python_gettext -- requests -- roman -- sgmllib3k -- simplejson -- soupsieve -- Unidecode -- urllib3 -- waitress -- WebOb -- WebTest -- WSGIProxy2 -- zipp diff --git a/coredev/plip-review.md b/coredev/plip-review.md deleted file mode 100644 index 267b559022..0000000000 --- a/coredev/plip-review.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -myst: - html_meta: - "description": "PLIP review" - "property=og:description": "PLIP review" - "property=og:title": "PLIP review" - "keywords": "PLIP, review, Plone Improvement Proposal, Plone" ---- - -```{todo} -Combine with PLIP page, remove obsolete technologies, go over language -``` - -# PLIP review - -A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. - - -## Expectations - -A good PLIP review takes about four hours. -Please plan accordingly. -When you are done, if you have access to core, commit the review to the `plips` folder, and reference the PLIP in your commit message. -If you do not have access, attach your review to the PLIP ticket itself. - - -## Setting up the environment - -Follow the instructions in {doc}`getting-started-with-development`. -You will need to checkout the branch to which the PLIP is assigned. -Instead of running the buildout with the default buildout file, you will run the configuration specific to that PLIP: - -```shell -./bin/buildout -c plips/plipXXXX.cfg -``` - - -## Functionality review - -This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. - - -### General - -- Does the PLIP actually do what the implementers proposed? - Are there incomplete variations? -- Were there any errors running buildout? - Did the migration(s) work? -- Do error and status messages make sense? - Are they properly internationalized? -- Are there any performance considerations? - Has the implementer addressed them, if so? - - -### Bugs - -- Are there any bugs? - Nothing is too big nor small. -- Do fields handle wacky data? - How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? - Is it too restrictive or not restrictive enough? - - -### Usability Issues - -- Is the implementation usable? -- How will novice end users respond to the change? -- Does this PLIP need a usability review? - If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. -- Is the PLIP consistent with the rest of Plone? - For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? - Is there any workflow that feels odd? -- Are there any new permissions and do they work properly? - Does their role assignment make sense? - - -### Documentation Issues - -- Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? -- Is the change itself properly documented? - -Report bugs or issues on GitHub as you would for any Plone bug. -Reference the PLIP in the bug, assign to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. -This way the implementer can find help if they need it. -Also set a priority for the ticket. -The PLIP will not be merged until all blockers and critical bugs are fixed. - - -### Code Review - - -#### Python - -- Is this code maintainable? -- Is the code properly documented? -- Does the code adhere to PEP8 standards (more or less)? -- Are they importing deprecated modules? - - -#### JavaScript - -- Does the JavaScript meet our set of JavaScript standards? - See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). -- Does the JavaScript work in all currently supported browsers? - Is it performant? - -```{todo} -Update links from Plone 5 Documentation to Plone 6 Documentation, when they exist. -See https://github.com/plone/documentation/issues/1330 -``` - -#### ME/TAL - -- Does the PLIP use views appropriately, avoiding too much logic? -- Is there any code in a loop that could potentially be a performance issue? -- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? diff --git a/coredev/plips.md b/coredev/plips.md deleted file mode 100644 index 90b071eacb..0000000000 --- a/coredev/plips.md +++ /dev/null @@ -1,299 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Improvement Proposals (PLIPs)" - "property=og:description": "Plone Improvement Proposals (PLIPs)" - "property=og:title": "Plone Improvement Proposals (PLIPs)" - "keywords": "Plone Improvement Proposal, PLIP)" ---- - -```{todo} -Needs language review -``` - -# Plone Improvement Proposals (PLIPs) - -A PLIP is a Plone Improvement Proposal. -It is a change to a Plone package that would affect everyone. -PLIPs go through a different process than bug fixes because of their broad reaching effect. -The Plone Framework Team reviews all PLIPs to be sure that it's in the best interest of the broader community to be implemented and that it is of high quality. - - -## Frequently asked questions about PLIPs - -This section provides detailed answers to common questions about PLIPs. - - -### PLIP or bugfix? - -In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. -When in doubt, submit it as a PLIP. -The Framework Team is eager to reduce its own workload and will reclassify it for you. -If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. -The key point here is that each change must be documented, allowing it to be tracked and understood. - - -### Who can submit PLIPs? - -Anyone who has signed a Plone Contributor Agreement can work on a PLIP. -Don't let the wording freak you out: signing the agreement is easy and you will get access almost immediately. - -You do not have to be the most amazing coder in the entire world to submit a PLIP. -The Framework Team is happy to help you at any point in the process. - -Submitting a PLIP can be a great learning process. -We encourage people of all backgrounds to submit a PLIP. -When the PLIP is accepted, a Framework Team member will "champion" your PLIP and be dedicated to its completion. - -PLIPs are not just for code monkeys. -If you have ideas on new interactions or UI your ideas are more than welcome. - -We will help you pair up with implementers if needed. - - -### What is a PLIP champion? - -When you submit your PLIP and it is approved, a Framework Team member who is especially excited about seeing the PLIP completed will be assigned to your PLIP as a champion. - -They are there to push you through completion, as well as answer any questions and provide guidance. - -A champion fulfill the following tasks. - -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. - -Keep in mind that champions are in passive mode by default. -If you need help or guidance, please reach out to them as soon as possible to activate help mode. - - -### Can I get involved in other ways? - -If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. -Ask one of the Framework Team members what PLIPs are available for review, or check the status of PLIPs at the [GitHub issues](https://github.com/plone/Products.CMFPlone/issues) page -for [Products.CMFPlone](https://github.com/Plone/Products.CMFPlone) -for [issues tagged with "03 type: feature (plip)"](https://github.com/plone/Products.CMFPlone/labels/03%20type%3A%20feature%20%28plip%29). - -Make sure to let us know you intend to review the PLIP by communicating that to the [Framework Team](https://community.plone.org/c/development/framework-team). - -Then, follow the instructions for {doc}`reviewing a PLIP `. - -Thank you in advance! - - -### When can I submit a PLIP? - -Today, tomorrow, any time! - -After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. - -You can begin work immediately, and we encourage submitting fast and furious. - - -### When is the PLIP due? - -**Summary: As soon as you get it done.** - -Technically, we want to see it completed for the release to which it's assigned. -We know that things get busy, and new problems may make PLIPs more complicated, and we will push it to the next release. - -In general, we don't want to track a PLIP for more than a year. - -If your PLIP is accepted and we haven't seen activity in over a year, we will probably ask you to restart the whole process. - - -### What happens if your PLIP is not accepted? - -If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. -It is often the case that there are competing implementations, and we want to see it vetted as an add-on before "blessing" a preferred implementation. - - -## Process Overview - -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. - In rare circumstances, a PLIP will be rejected. - This is usually the result of the developer not responding to feedback or dropping out of the process. - Hang in there! -9. After all other PLIPs are merged, a release is cut. - Standby for bugs! - - -(how-to-submit-a-plip)= - -## How to submit a PLIP - -Whether you want to update the default theme, or rip out a piece of architecture, everyone should go through the PLIP process. -If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team). - -A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues/new) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. - -To get started, open a new issue. -The issue will be prefilled with headings and comments for a bug or a PLIP. -Remove the bug part. -Fill in all applicable fields. -After submitting, select the tag `03 type: feature (plip)` for the issues. - -When writing a PLIP, be as specific and to-the-point as you can. -Remember your audience. -To get support for your proposal, people will have to be able to read it! - -A good PLIP is sufficiently clear for a knowledgeable Plone user to understand the proposed changes, and sufficiently detailed for the release manager and other developers to understand the full impact the proposal would have on the code base. - -You don't have to list every line of code that needs to be changed, but you should also give an indication that you have some idea of how the change can be feasibly implemented. - -After your PLIP is written, solicit feedback on your idea on the [Plone Community Forum](https://community.plone.org/). -In this vetting process, you want to make sure that the change won't adversely affect other people on accident. -Others may be able to point out risks or even offer up better or existing solutions. - -Please note a few things: - -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. - -We will send the PLIP back to you if it is not filled in. -Currently, this is just someone else who thinks your PLIP is a good idea, a +1. - -In the near future, we will start asking that the seconder is either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. - - -### Evaluating PLIPs - -After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. -If the PLIP is not accepted, please don't be sad! - -We encourage most PLIPs to go through the add-on process at first, if at all possible, to make sure the majority of the community uses it. - -All communication with you occurs on the PLIP issue itself. -Please keep your eyes and inbox open for changes. - -These are the criteria by which the framework team will review your work: - -- What is size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? - -See the {doc}`plip-review` page for more information. - - -## Implementing your PLIP - -You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. - - -### General Rules - -- Any new packages must be in a branch in the `plone` namespace in GitHub. - You don't have to develop there, but it must be there when submitted. - We recommend using branches off of the repositories under the Plone GitHub organization, and will detail that below. -- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. -- Any new code must: - - - Be {doc}`properly documented `. - - Have clear code. - - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). - For convenience and better code quality use Python, JavaScript, and other code linting plugins in your editor. - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). - -```{todo} -Update links from Plone 5 to Plone 6 Documentation, once content is migrated. -See https://github.com/plone/documentation/issues/1330 and other issues. -``` - - -### Creating a new PLIP branch - -Create a buildout configuration file for your PLIP in the `plips` folder. -Give it a descriptive name, starting with the PLIP number, for example, {file}`plip-1234-widget-frobbing.cfg`. - -The PLIP number is your PLIP's issue number. - -This file will define the branches you're working with in your PLIP, along with other buildout configuration. - -It should look something like the following, such as in a file {file}`plips/plip-1234-widget-frobbing.cfg`. - -```ini -[buildout] -extends = plipbase.cfg -auto-checkout += - plone.somepackage - plone.app.someotherpackage - -[sources] -plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-1234-widget-frobbing -plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-1234-widget-frobbing - -[instance] -eggs += - plone.somepackage - plone.app.someotherpackage -zcml += - plone.somepackage - plone.app.someotherpackage -``` - -Use the same naming convention when you branch existing packages. -You should always branch packages when working on PLIPs. - - -### Working on a PLIP - -To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: - -```shell -virtualenv . -./bin/pip install -r requirements.txt -./bin/buildout -c plips/plip-1234-widget-frobbing.cfg -``` - -If you are using a {file}`local.cfg` to extend your PLIP file with some changes that you do not want to commit accidentally, be aware that you need to override some settings from {file}`plipbase.cfg` to avoid some files being created in the {file}`plips` directory or in the directory above the buildout directory. -This is done as shown below. - -```ini -[buildout] -extends = plips/plip-1234-widget-frobbing.cfg -develop-eggs-directory = ./develop-eggs -bin-directory = ./bin -parts-directory = ./parts -sources-dir = ./src -installed = .installed.cfg - -[instance] -var = ./var -``` - - -### Finishing up - -Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. -This file should be called {file}`plip__notes.txt`. -This should include, but is not limited to: - -- URLs pointing to all documentation created and updated -- Any concerns and issues still remaining -- Any weird buildout things - -Once you have finished, update your PLIP issue to indicate that it is ready for review. -The Framework Team will assign 2-3 people to review your PLIP. -They will follow the guidelines listed at {doc}`plip-review`. - -After the PLIP has been accepted by the Framework Team and the release manager, you will be asked to merge your work into the main development line. -Merging the PLIP in is not the hardest part, but you must think about it when you develop. - -You'll have to interact with a large number of people to get it all set up. -The merge may cause problems with other PLIPs coming in. -During the merge phase you must be prepared to help out with all the features and bugs that arise. - -If all went as planned, the next Plone release will carry on with your PLIP in it. -You'll be expected to help out with that feature after it's been released (within reason). diff --git a/coredev/release.md b/coredev/release.md deleted file mode 100644 index 3d4ff8ac87..0000000000 --- a/coredev/release.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone release process" - "property=og:description": "Plone release process" - "property=og:title": "Plone release process" - "keywords": "Plone, release, process" ---- - -```{todo} -Can stay, as it needs a place to live. Check in with Release Managers to update content, if needed -``` - -# Plone release process - -This chapter describes the process to release Plone and its packages. - - -## Release process for Plone packages - -To keep the Plone software stack maintainable, the Python egg release process must be automated to a high degree. -This happens by enforcing Python packaging best practices, and then making automated releases using [`zest.releaser`](https://github.com/zestsoftware/zest.releaser/). - -This is extended with Plone coredev specific features by [`plone.releaser`](https://github.com/plone/plone.releaser). - -Anyone with necessary PyPI permissions must be able to make a new release by running the `fullrelease` command. -This command includes the following requirements. - -```{note} -All files mentioned in this list may be written in Markdown or reStructuredText and have the appropriate file name suffix. -``` - -- All releases must be hosted on PyPI. -- All versions must be tagged in version control. -- Each package must have a {file}`README` file with links to the version control repository and issue tracker. -- {file}`CHANGES` ({file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. -- {file}`CHANGES` must contain release dates. -- {file}`README` and {file}`CHANGES` must be visible on PyPI. -- Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. - The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. -- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). - -```{seealso} -[High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). -``` - - -## Special packages - -The Plone Release Team releases the core Plone packages. -Several others also have the rights to release individual packages on [PyPI](https://pypi.org/). -If you have those rights on your account, you should feel free to make releases. - -Some packages need special care, or should be done only by specific people, as they know what they are doing. -These are: - -`Products.CMFPlone`, `Plone`, and `plone.app.upgrade` -: Please leave these to the release manager, Eric Steele. - -`plone.app.locales` -: Please leave this to the i18n team lead, Vincent Fretin. - - -## Plone core release process checklist - -1. Check Jenkins status. - Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org/). - It should be green, but if it is not, fix the problem first. - -2. Check out `buildout.coredev`. - - ```shell - git clone git@github.com:plone/buildout.coredev.git - cd buildout.coredev - git checkout 5.1 - python bootstrap.py - bin/buildout -c buildout.cfg - ``` - -3. Check packages for updates. - Check all packages for updates, add to or remove from `checkouts.cfg` accordingly. - This script may help: - - ```shell - bin/manage report --interactive - ``` - - This step should not be needed, because we do the check for every single commit, but people may still have forgotten to add a package to the `checkouts.cfg` file. - -4. Check packages individually. - - Use the `bin/fullrelease` script from the core development buildout. - This includes extra checks that we have added in `plone.releaser`. - It guides you through all the next steps. - - 1. Check changelog. - Check if `CHANGES` is up-to-date. - All changes since the last release should be included. - A "Fixes" or "New" header should be included, with the relevant changes under it. - Upgrade notes are best placed here as well. - Compare `git log HEAD...` with `CHANGES`, or from `zest.releaser` use the command `lasttaglog `. - 2. Run [pyroma](https://pypi.org/project/pyroma/). - 3. Run [check-manifest](https://pypi.org/project/check-manifest/). - 4. Check package "best practices" (`README`, `CHANGES`, `src` directory). - 5. Check if the version in `setup.py` is correct and follows our versioning best practice. - 6. Make a release (zest.releaser: `bin/fullrelease`) - 7. Remove packages from auto-checkout section in `checkouts.cfg` and update `versions.cfg`. - -5. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. -6. Update CMFPlone version in `profiles/default/metadata.xml`. -7. Create an issue in to ask the i18n team lead @vincentfretin to do a `plone.app.locales` release. -8. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). - - 1. Copy all core packages there. - 2. Possibly make an alpha or beta release of CMFPlone. - 3. Copy the `versions.cfg` file from coredev to there. - -9. Write an email to the Plone developers list announcing a pending release. -10. Update `plone.app.locales` version. -11. Create a unified changelog. - - ```shell - bin/manage changelog - ``` - -12. Make the final release on dist.plone.org (remove "-pending") -13. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). -14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). -15. Create a release page on [plone.org](https://plone.org/download/releases) -16. Send links to the installers list at plone-installers@lists.sourceforge.net. -17. Wait for installers to be uploaded to Launchpad, with a link to the plone.org release page. -18. Publish release page on plone.org. -19. Update plone.org homepage links to point to the new release. -20. Send out announcement to the plone-announce email distribution list. -21. Update #plone topic (obsolete? maybe announce to Discord?) -22. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. diff --git a/coredev/roboto.md b/coredev/roboto.md deleted file mode 100644 index ef2e7a1091..0000000000 --- a/coredev/roboto.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -myst: - html_meta: - "description": "Mr. Roboto" - "property=og:description": "Mr. Roboto" - "property=og:title": "Mr. Roboto" - "keywords": "Mr. Roboto, mr.roboto, Plone" ---- - -```{todo} -Needs content review, it looks highly outdated with references to CVS, kgs and other obsolete tech -``` - -# Mr. Roboto - -```{todo} -Add brief description of what is Mr. Roboto and what it does. -``` - -## GitHub push - -When a push happens on GitHub, `mr.roboto` is triggered and it starts to analyze the push. - -- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. - In this case, we send to `plone-cvs` the commit to keep track of the commits on that list. -- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. - This kgs job is a snapshot of the last working version of the `buildout.coredev` with the newest version of the package that is involved on the push. - These jobs are really fast, as we only test the package applied to the kgs Plone and Python version `coredev` buildout. -- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at http://jenkins.plone.org/roboto/plips. - -```{todo} -`http://jenkins.plone.org/roboto/plips` is obsolete, and returns a 404 not found. -``` - - -## Job finishes - -When Jenkins finishes a job, it makes a callback to `mr.roboto`, which in turn does the following: - -- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. - It does this one time only, with all the information, so no more empty mails from the GitHub notification system. -- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. - We also send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. -- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. - -For all kgs jobs jenkins sends an email to the author with the results when is finished. - -All the notifications have an URL similar to http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10. - -```{todo} -http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 is obsolete, and returns a 404 not found. -``` - -On this URL, there is the commit hash, who committed it, the diff, the files, and the result for each Jenkins job. - -- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. -- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. -- The author receives the results of tests failing against kgs after ten minutes after the push. - -```{note} -In case of integration errors with other packages that may fail because of the push, kgs will not be aware of that. -It's important that at the end (and after the fifty minutes that takes the `coredev` jobs to complete), that you also check the latest version of `coredev` with your push. -``` diff --git a/coredev/troubleshooting.md b/coredev/troubleshooting.md deleted file mode 100644 index 61a94d3f3d..0000000000 --- a/coredev/troubleshooting.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -myst: - html_meta: - "description": "Troubleshooting development issues in Plone" - "property=og:description": "Troubleshooting development issues in Plone" - "property=og:title": "Troubleshooting development issues in Plone" - "keywords": "Troubleshooting, development issues, Plone" ---- - -```{todo} -Needs review. In general, a 'troubleshooting' page is nice, but this looks outdated -``` - -# Troubleshooting - -This chapter describes how to troubleshoot development issues in Plone. - - -## Buildout issues - -Buildout can be frustrating for those unfamiliar with parsing through autistic robot language. -These errors are almost always a quick fix, and a little bit of understanding goes a long way. - - -### Errors running `bootstrap.py` - -You may not even get to running buildout, and then you will already have an error. -Let's take this one for example: - -```console - File "/usr/local/lib/python2.6/site-packages/distribute-0.6.13-py2.6.egg/pkg_resources.py", line 556, in resolve - raise VersionConflict(dist,req) # XXX put more info here - pkg_resources.VersionConflict: (zc.buildout 1.5.1 (/usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg), Requirement.parse('zc.buildout==1.5.2')) -``` - -Buildout has simply noticed that the version of buildout required by the file `bootstrap.py` you are trying to run does not match the version of buildout in your Python library. -In the error above, your system has buildout 1.5.1 installed and the `bootstrap.py` file wants to run with 1.5.2. - -To fix, you have a couple options. -First, you can force buildout to run with the version you already have installed by invoking the version tag. -This tells your Plone `bootstrap.py` file to play nicely with the version that you already have installed. -In the case of the error pasted above, that would be: - -```shell -python bootstrap.py --version=1.5.1 -``` - -I personally know that versions 1.4.4, 1.5.1, and 1.5.2 all work this way. - -The other option is to delete your current egg and force the upgrade. -In the case of the error above, delete the egg the system currently has, for example: - -```shell -rm -rf /usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg -``` - -When you rerun bootstrap, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. - -Do one of those and re-run bootstrap. - -One other thing of note is that running bootstrap effectively ties that Python executable and all of its libraries to your buildout. -If you have several Python installs, and want to switch which Python is tied to your buildout, simply rerun `bootstrap.py` with the new Python (and then rerun buildout). -You may get the same error above again, but now that you know how to fix it, you can spend that time drinking beer instead of smashing your keyboard. - -Hooray! - - -### When `mr.developer` is unhappy - -`mr.developer` is never unhappy, except when it is. -Although this technically isn't a buildout issue, it happens when running buildout, so I'm putting it under buildout issues. - -When working with the dev instance, especially with all the moving back and forth between GitHub and Subversion, you may have an old copy of a `src` package. -The error looks like: - -```console -mr.developer: Can't update package 'Products.CMFPlone' because its URL doesn't match. -``` - -As long as you don't have any pending commits, you just need to remove the package from {file}`src/` and it will recheck it out for you when it updates. - -You can also get such fun errors as: - -```console -Link to http://sphinx.pocoo.org/ ***BLOCKED*** by --allow-hosts -``` - -These are OK to ignore if and only if the lines following it say: - -```console -Getting distribution for 'Sphinx==1.0.7'. -Got Sphinx 1.0.7. -``` - -If buildout ends with warning you that some packages could not be downloaded, then chances are that package wasn't downloaded. -This is bad and could cause all sorts of whack out errors when you start or try to run things because it never actually downloaded the package. - -There are two ways to get this error to go away. - -The first is to delete all instances of host filtering. -Go through all the files and delete any lines which say `allow-hosts =` and `allow-hosts +=`. -In theory, by restricting which hosts you download from, buildout will go faster. -The point is that they are safely deletable. - -The second option is to allow the host that it is pointing to by adding something like this to your `.cfg`: - -```cfg -allow-hosts += sphinx.pocoo.org -``` - -Again, this is only necessary if the package wasn't found in the end. - - -### `mr.developer` path errors - -```console -ERROR: You are not in a path which has mr.developer installed (:file:`.mr.developer.cfg` not found). -``` - -When running any {command}`./bin/develop` command. - -To fix, do: - -```shell -ln -s plips/.mr.developer.cfg -``` - - -## Other random issues - -```{TODO} -These need to be revalidated -``` - - -### Dirty packages - -```console -ERROR: Can't update package 'Some package', because it's dirty. -``` - - -#### Fix - -`mr.developer` is complaining because a file has been changed or added, but not committed. - -Use `bin/develop update --force`. -Adding `*.pyc *~.nib *.egg-info .installed.cfg *.pt.py *.cpt.py *.zpt.py *.html.py *.egg` to your subversion configuration's `global-ignores` has been suggested as a more permanent solution. - - -### No module named zope 2 - -```console -ImportError: No module named Zope2" when building using a PLIP cfg file. -``` - -Appears to not actually be the case. -Delete {file}`mkzopeinstance.py` from {file}`bin/`, and rerun buildout to correct this if you're finding it irksome. - - -### Can't open file '/Startup/run.py' - -Two possible fixes. - -If you use Python 2.4 by mistake, use 2.6 instead. - -Or you may need to make sure you run `bin/buildout …` after `bin/develop …`. -Try removing {file}`parts/*`, {file}`bin/*`, {file}`.installed.cfg`, then re-bootstrap and re-run buildout, develop, buildout. - - -### Missing PIL - -{file}`pil.cfg` is included within this buildout to aid in PIL installation. -Run {command}`bin/buildout -c pil.cfg` to install. -This method does not work on Windows. -We're unable to run it by default. - - -### Modified egg issues - -{command}`bin/develop status` is showing that the `Products.CMFActionIcons` egg has been modified, but I haven't touched it. -And this is preventing `bin/develop up` from updating all the eggs. - -#### Fix - -Edit {file}`~/.subversion/config` and add `eggtest\*.egg` to the list of `global-ignores`.