From 7ce3cdf313dccf75f5a4b8c5b78d2b546959e651 Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 09:26:49 +0200 Subject: [PATCH 01/13] initial push --- docs/conf.py | 2 ++ docs/contributing/core/index.md | 24 +++++++++++++++++++++ docs/contributing/index.md | 38 +++++++++++++-------------------- requirements.txt | 1 + styles/Vocab/Plone/accept.txt | 1 + 5 files changed, 43 insertions(+), 23 deletions(-) create mode 100644 docs/contributing/core/index.md diff --git a/docs/conf.py b/docs/conf.py index 00877dcf41..7a660aaae0 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", ] @@ -329,6 +330,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/index.md b/docs/contributing/core/index.md new file mode 100644 index 0000000000..295bc7be27 --- /dev/null +++ b/docs/contributing/core/index.md @@ -0,0 +1,24 @@ +--- +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`. + +## Additional material + +```{toctree} +:maxdepth: 1 + +package-dependencies +release +``` 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/requirements.txt b/requirements.txt index a6c516054c..2adffd0438 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 vale==2.30.0 diff --git a/styles/Vocab/Plone/accept.txt b/styles/Vocab/Plone/accept.txt index c93207b679..bf29fd4c43 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/Vocab/Plone/accept.txt @@ -22,6 +22,7 @@ Mockup npm nvm Pastanaga +PLIP(s) Plone pluggab(le|ility) programatically From 47342808444760c0b7b7fc741b0f5208f2fb2b13 Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 09:37:20 +0200 Subject: [PATCH 02/13] Insert notes on keeping or removing --- 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 ++++++++++---------- 11 files changed, 359 insertions(+), 383 deletions(-) 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..b2600c741e 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 packagaes 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 From 71cdf6a4cbc6272a8a1aa62fb1854974d2f72761 Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 09:44:31 +0200 Subject: [PATCH 03/13] some more notes on what to do with coredev pages --- coredev/plip-review.md | 60 ++++++++++++--------------- coredev/plips.md | 84 ++++++++++++++++---------------------- coredev/release.md | 71 ++++++++++++++++---------------- coredev/roboto.md | 27 ++++++------ coredev/troubleshooting.md | 15 ++----- 5 files changed, 118 insertions(+), 139 deletions(-) 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. From 9557b33f534fbcfdc31f3579562c1bc23e9411a5 Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 10:50:13 +0200 Subject: [PATCH 04/13] start integrating content from intro.rst --- docs/contributing/core/index.md | 47 +++++++++++++++++++++++ docs/contributing/core/troubleshooting.md | 12 ++++++ 2 files changed, 59 insertions(+) create mode 100644 docs/contributing/core/troubleshooting.md diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 295bc7be27..70fd04cc0a 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -14,6 +14,53 @@ It's primarily a technical resource for setting up your development environment, It expands upon {doc}`/contributing/index` and, where applicable, {doc}`/contributing/first-time`. +## 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) + +## 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/) + +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](http://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. +I.e. 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 is your first pull (~20 mins). +Once that is done pulling down eggs, +you can start your new instance with:: + +```shell +./bin/instance fg +``` + +or as WSGI service with:: + +```shell +./bin/wsgi +``` + +The default username/password for a dev instance is **admin/admin**. + ## Additional material ```{toctree} diff --git a/docs/contributing/core/troubleshooting.md b/docs/contributing/core/troubleshooting.md new file mode 100644 index 0000000000..ac6d65f9c8 --- /dev/null +++ b/docs/contributing/core/troubleshooting.md @@ -0,0 +1,12 @@ +--- +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. From ca9d4400b18226974c10ab1c686f5fbee2d95fb2 Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 11:57:52 +0200 Subject: [PATCH 05/13] integrate gettingstartedwithdevelopent content --- .../core/continuous-integration.md | 10 + docs/contributing/core/index.md | 192 +++++++++++++++++- docs/contributing/core/mrdeveloper.md | 10 + 3 files changed, 208 insertions(+), 4 deletions(-) create mode 100644 docs/contributing/core/continuous-integration.md create mode 100644 docs/contributing/core/mrdeveloper.md diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md new file mode 100644 index 0000000000..1d39a4f1e0 --- /dev/null +++ b/docs/contributing/core/continuous-integration.md @@ -0,0 +1,10 @@ +--- +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 diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 70fd04cc0a..99d471e529 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -26,6 +26,9 @@ If you are triaging or fixing bugs, keep in mind that Plone has a [version suppo - {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/) in order to compile ZODB, Zope and lxml. 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](http://en.wikipedia.org/wiki/Backporting) as necessary. @@ -45,9 +48,8 @@ cd ./plone6devel 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 (~20 mins). -Once that is done pulling down eggs, -you can start your new instance with:: +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 @@ -59,7 +61,189 @@ or as WSGI service with:: ./bin/wsgi ``` -The default username/password for a dev instance is **admin/admin**. +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 (CI) setup and follows CI rules. + +When you push a change to any Plone package, the 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. + +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. +The 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}`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 are running 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 very 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 very 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 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`. + +## 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 pdbs? +- 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 of these questions, 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 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. + +## 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 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. + +## 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. ## Additional material diff --git a/docs/contributing/core/mrdeveloper.md b/docs/contributing/core/mrdeveloper.md new file mode 100644 index 0000000000..da2120b066 --- /dev/null +++ b/docs/contributing/core/mrdeveloper.md @@ -0,0 +1,10 @@ +--- +myst: + html_meta: + "description": "mr.developer" + "property=og:description": "mr.developer" + "property=og:title": "mr.developer" + "keywords": "mr.developer" +--- + +# `mr.developer` From f9cac3ebafd4a883c0a509960720fb13315bb78d Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 13:13:35 +0200 Subject: [PATCH 06/13] style changes with Vale checking --- docs/contributing/core/index.md | 49 +++++++++++++++++---------------- docs/glossary.md | 11 ++++++-- styles/Vocab/Plone/accept.txt | 4 +++ 3 files changed, 38 insertions(+), 26 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 99d471e529..bf4475817e 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -16,7 +16,7 @@ It expands upon {doc}`/contributing/index` and, where applicable, {doc}`/contrib ## 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) +If you are fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule) ## Dependencies @@ -28,13 +28,14 @@ If you are triaging or fixing bugs, keep in mind that Plone has a [version suppo - [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/) in order to compile ZODB, Zope and lxml. +- [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. -We recommend fixing the bug on the latest branch and then [backporting](http://en.wikipedia.org/wiki/Backporting) as necessary. +Start with fixing the bug on the latest branch and then [backporting](http://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. -I.e. at the moment 6.0 is the actively maintained stable branch and 6.1 is the future, currently unstable, active development 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: @@ -48,14 +49,14 @@ cd ./plone6devel 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: +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 WSGI service with:: +or as {term}`WSGI` service with:: ```shell ./bin/wsgi @@ -96,15 +97,15 @@ Make sure to rerun buildout if you were in a different branch earlier to get the ## Jenkins and mr.roboto -Plone has a continuous integration (CI) setup and follows CI rules. +Plone has a continuous integration ({term}`CI`) setup and follows CI rules. -When you push a change to any Plone package, the 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. +When you push a change to any Plone package, the testing/CI package `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). 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. -The 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: +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. Check Jenkins first. 2. Always run all commit tests locally before committing. @@ -142,7 +143,7 @@ Then rerun buildout to get the source packages: For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. -## Testing Locally +## Testing locally To run a test for the specific module you modify: @@ -169,7 +170,7 @@ 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. +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. @@ -178,19 +179,19 @@ This change note will be collated for the next Plone release and is important fo 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 very top of {file}`CHANGES.rst`. +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 very quickly. +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 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`. +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 @@ -198,20 +199,20 @@ 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 pdbs? +- 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 of these questions, then you are ready to push your changes! +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 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. + 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 @@ -234,15 +235,15 @@ 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. +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. -We don't have integration with GitHub yet so it's a nice way to track changes. +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 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/styles/Vocab/Plone/accept.txt b/styles/Vocab/Plone/accept.txt index bf29fd4c43..e73ecaa4be 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/Vocab/Plone/accept.txt @@ -8,6 +8,7 @@ accessor APIs [Aa]sync [Bb]ackend +backport(ed|ing) Barceloneta [Bb]oolean buildout @@ -17,7 +18,9 @@ folderish fieldset getter JavaScript +[Jj]enkins jQuery +libxslt Mockup npm nvm @@ -35,6 +38,7 @@ RichText Sass Schuko subfolder +[Tt]owncrier transpile[dr]{0,1} unregister UUID From 6c9e79566a842ba5b6367030082f1d12dfde8d4d Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 17:45:02 +0200 Subject: [PATCH 07/13] more fixes --- coredev/guidelines.md | 2 +- docs/conf.py | 5 + .../core/continuous-integration.md | 88 ++++ docs/contributing/core/index.md | 17 +- docs/contributing/core/mrdeveloper.md | 26 ++ .../contributing/core/package-dependencies.md | 399 ++++++++++++++++++ docs/contributing/core/release.md | 128 ++++++ docs/contributing/core/troubleshooting.md | 43 ++ 8 files changed, 693 insertions(+), 15 deletions(-) create mode 100644 docs/contributing/core/package-dependencies.md create mode 100644 docs/contributing/core/release.md diff --git a/coredev/guidelines.md b/coredev/guidelines.md index b2600c741e..a931c3eb12 100644 --- a/coredev/guidelines.md +++ b/coredev/guidelines.md @@ -9,7 +9,7 @@ myst: ```{todo} All this can go, it's redundant. -IMPORTANT: it does need a rewrite on 6.docs.plone.org as there are many packagaes in the wild that link to it. +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! diff --git a/docs/conf.py b/docs/conf.py index 7a660aaae0..f63ffba6ca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -180,6 +180,11 @@ "fawrench": '', } +mermaid_params = [ + "mermaid_version", + "10.9.1", +] + # -- Intersphinx configuration ---------------------------------- # This extension can generate automatic links to the documentation of objects diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md index 1d39a4f1e0..ed195183b9 100644 --- a/docs/contributing/core/continuous-integration.md +++ b/docs/contributing/core/continuous-integration.md @@ -8,3 +8,91 @@ myst: --- # 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/index.md b/docs/contributing/core/index.md index bf4475817e..8698f32bb2 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -102,20 +102,6 @@ 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` 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). -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. -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. 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}`continuous-integration` for more information. ## Check out packages to fix @@ -251,6 +237,9 @@ It also lets the reporter know that you care. ```{toctree} :maxdepth: 1 +continuous-integration +mrdeveloper +troubleshooting package-dependencies release ``` diff --git a/docs/contributing/core/mrdeveloper.md b/docs/contributing/core/mrdeveloper.md index da2120b066..ce14a624dd 100644 --- a/docs/contributing/core/mrdeveloper.md +++ b/docs/contributing/core/mrdeveloper.md @@ -8,3 +8,29 @@ myst: --- # `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..b8296373a0 --- /dev/null +++ b/docs/contributing/core/package-dependencies.md @@ -0,0 +1,399 @@ +--- +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: + +```{note} +The mermaid syntax below needs a newer version of mermaid (preferably 10.9.1) before it can handle block diagrams +``` + +```{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 + core + + space + cmfplone["Products.CMFPlone"] + + space:2 + +layer + +space + + plonebase["plone.base"] + space + foundations["The Foundations"] + + Plone --> Distributions + dist --> core + cmfplone --> layer + core --> cmfplone + layer --> plonebase + plonebase --> foundations + + style cmfplone fill:#ff0 + style plonebase fill:#ff0 + +``` + +``` +┌────────────────────────────┐ +│ "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 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/release.md b/docs/contributing/core/release.md new file mode 100644 index 0000000000..005f69d5ab --- /dev/null +++ b/docs/contributing/core/release.md @@ -0,0 +1,128 @@ +--- +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 (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 . +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. 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 index ac6d65f9c8..7a08cfa170 100644 --- a/docs/contributing/core/troubleshooting.md +++ b/docs/contributing/core/troubleshooting.md @@ -10,3 +10,46 @@ myst: # 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). From f99e42048e9441ff660c4ea3e0837c8492678f33 Mon Sep 17 00:00:00 2001 From: polyester Date: Sun, 16 Jun 2024 18:08:06 +0200 Subject: [PATCH 08/13] WIP: include plips page --- docs/contributing/core/plips.md | 274 ++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) create mode 100644 docs/contributing/core/plips.md diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md new file mode 100644 index 0000000000..ee101f6a8c --- /dev/null +++ b/docs/contributing/core/plips.md @@ -0,0 +1,274 @@ +--- +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 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 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 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. +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 experts. +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 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 sad! + +Most PLIPs may 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 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 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 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 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). From b9d4b1985cda7ffda51f72752bc442644270dcc8 Mon Sep 17 00:00:00 2001 From: polyester Date: Mon, 17 Jun 2024 11:35:18 +0200 Subject: [PATCH 09/13] get latest (and pinned) mermaid.js --- docs/conf.py | 5 +- .../contributing/core/package-dependencies.md | 81 ++++--------------- requirements.txt | 2 +- 3 files changed, 18 insertions(+), 70 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f63ffba6ca..4a45439c63 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -180,10 +180,7 @@ "fawrench": '', } -mermaid_params = [ - "mermaid_version", - "10.9.1", -] +mermaid_version = "10.9.1" # -- Intersphinx configuration ---------------------------------- diff --git a/docs/contributing/core/package-dependencies.md b/docs/contributing/core/package-dependencies.md index b8296373a0..d2270a3955 100644 --- a/docs/contributing/core/package-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -36,13 +36,8 @@ Since Plone consists of a lot of packages, it is complex to untangle those. A base mental model for how Plone is organized in Plone 6 is shown in the following diagram: -```{note} -The mermaid syntax below needs a newer version of mermaid (preferably 10.9.1) before it can handle block diagrams -``` - ```{mermaid} - - block-beta +block-beta columns 1 Plone["Plone
the integraton of both distributions in one release"] @@ -53,21 +48,32 @@ The mermaid syntax below needs a newer version of mermaid (preferably 10.9.1) be plone.classic end space - core - + block:core + coreaddons["Core addons"] + coreapi["Core APIs"] + end space cmfplone["Products.CMFPlone"] space:2 -layer + 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 @@ -80,61 +86,6 @@ space ``` -``` -┌────────────────────────────┐ -│ "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 there are two packages as dividing lines: 1. `Products.CMFPlone` diff --git a/requirements.txt b/requirements.txt index 2adffd0438..a0d60d48fa 100644 --- a/requirements.txt +++ b/requirements.txt @@ -23,5 +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 +sphinxcontrib.mermaid==0.9.2 vale==2.30.0 From 348d8320c12ef3d64e54f0c1d270b33f9040f178 Mon Sep 17 00:00:00 2001 From: polyester Date: Mon, 17 Jun 2024 13:39:58 +0200 Subject: [PATCH 10/13] adding pages 'documentation', 'plips' and 'plip-review' --- docs/contributing/core/documentation.md | 81 +++++++++++++++++++ docs/contributing/core/index.md | 3 + docs/contributing/core/plip-review.md | 101 ++++++++++++++++++++++++ docs/contributing/core/plips.md | 42 +++++----- styles/Vocab/Plone/accept.txt | 1 + 5 files changed, 208 insertions(+), 20 deletions(-) create mode 100644 docs/contributing/core/documentation.md create mode 100644 docs/contributing/core/plip-review.md diff --git a/docs/contributing/core/documentation.md b/docs/contributing/core/documentation.md new file mode 100644 index 0000000000..ff560b0e03 --- /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, 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 index 8698f32bb2..42c681ec2d 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -239,7 +239,10 @@ It also lets the reporter know that you care. continuous-integration mrdeveloper +documentation troubleshooting +plips +plip-review package-dependencies release ``` diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md new file mode 100644 index 0000000000..48fdfb53cc --- /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](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 index ee101f6a8c..7f7b766d9f 100644 --- a/docs/contributing/core/plips.md +++ b/docs/contributing/core/plips.md @@ -9,10 +9,11 @@ myst: # Plone Improvement Proposals (PLIPs) -A PLIP is a Plone Improvement Proposal. +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 be sure that it's in the best interest of the broader community to be implemented and that it is of high quality. +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 @@ -34,29 +35,29 @@ 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. -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. + +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. -We will help you pair up with implementers if needed. +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 who is especially excited about seeing the PLIP completed will be assigned to your PLIP as a 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 push you through completion, as well as answer any questions and provide guidance. +They are there to help you through completion, answer questions and provide guidance. -A champion fulfill the following tasks. +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. +- 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 in passive mode by default. -If you need help or guidance, please reach out to them as soon as possible to activate help mode. +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? @@ -148,16 +149,16 @@ In the near future, the seconder should either a coding partner, or someone who ### 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! +If the PLIP is not accepted, please don't be discouraged! -Most PLIPs may first start as an add-on, if possible, to make sure it works in practice. +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 size and status of the work needed to be done? +- 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? @@ -180,9 +181,8 @@ You can start the development at any time, but if you are going to modify Plone - 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). + - 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. @@ -191,7 +191,8 @@ 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. +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. @@ -267,7 +268,8 @@ After the PLIP has been accepted by the Framework Team and the release managers, 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. + +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. diff --git a/styles/Vocab/Plone/accept.txt b/styles/Vocab/Plone/accept.txt index e73ecaa4be..15b0ecf039 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/Vocab/Plone/accept.txt @@ -11,6 +11,7 @@ APIs backport(ed|ing) Barceloneta [Bb]oolean +bugfix buildout cacheable doctest From e5cfed1e8644dbc32b0b10cc0cc8bcb1a9820dd6 Mon Sep 17 00:00:00 2001 From: polyester Date: Mon, 17 Jun 2024 13:53:55 +0200 Subject: [PATCH 11/13] fix typo and add linkcheck-ignore --- docs/conf.py | 1 + docs/contributing/core/plip-review.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 4a45439c63..9e0d74a2e1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,6 +100,7 @@ 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 ] linkcheck_anchors = True linkcheck_timeout = 5 diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md index 48fdfb53cc..670838c932 100644 --- a/docs/contributing/core/plip-review.md +++ b/docs/contributing/core/plip-review.md @@ -16,7 +16,7 @@ A Plone Improvement Proposal (PLIP) is a formal process to propose a change to i 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](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 From a526ecb529f987b1d94a388839d86b0344e4af9f Mon Sep 17 00:00:00 2001 From: polyester Date: Mon, 17 Jun 2024 14:24:39 +0200 Subject: [PATCH 12/13] link fixes --- docs/conf.py | 1 + docs/contributing/core/documentation.md | 2 +- docs/contributing/core/index.md | 2 +- docs/contributing/core/release.md | 13 ++++++------- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9e0d74a2e1..a5a763de42 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,6 +101,7 @@ 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 diff --git a/docs/contributing/core/documentation.md b/docs/contributing/core/documentation.md index ff560b0e03..740b868815 100644 --- a/docs/contributing/core/documentation.md +++ b/docs/contributing/core/documentation.md @@ -60,7 +60,7 @@ 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, 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://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 diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 42c681ec2d..3b91e5686d 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -31,7 +31,7 @@ If you are fixing bugs, keep in mind that Plone has a [version support policy](h - [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](http://en.wikipedia.org/wiki/Backporting) as necessary. +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. diff --git a/docs/contributing/core/release.md b/docs/contributing/core/release.md index 005f69d5ab..f9eba0c43b 100644 --- a/docs/contributing/core/release.md +++ b/docs/contributing/core/release.md @@ -116,13 +116,12 @@ These are: bin/manage changelog ``` -12. Make the final release on dist.plone.org (remove "-pending") +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. 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. -20. Send out announcement to the plone-announce email distribution list. -21. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. +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. From 5b9ecb3662db78bb673d339a5f1adf25f8c4dbfa Mon Sep 17 00:00:00 2001 From: polyester Date: Mon, 17 Jun 2024 15:44:07 +0200 Subject: [PATCH 13/13] link to mr.roboto --- docs/contributing/core/index.md | 2 +- submodules/plone.api | 2 +- submodules/plone.restapi | 2 +- submodules/volto | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 3b91e5686d..6c505c50ad 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -99,7 +99,7 @@ Make sure to rerun buildout if you were in a different branch earlier to get the 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` starts running all the tests to make sure that you don't break anything. +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. diff --git a/submodules/plone.api b/submodules/plone.api index b114c588c6..8b92390306 160000 --- a/submodules/plone.api +++ b/submodules/plone.api @@ -1 +1 @@ -Subproject commit b114c588c6b3b3984c2d682db4098912e87d0a48 +Subproject commit 8b92390306e036d48d1665cb4de74bff152a32e5 diff --git a/submodules/plone.restapi b/submodules/plone.restapi index 9d11653fe2..c7b8e076de 160000 --- a/submodules/plone.restapi +++ b/submodules/plone.restapi @@ -1 +1 @@ -Subproject commit 9d11653fe2da0c50ee4d74bef1d8a416879c4168 +Subproject commit c7b8e076deeb3c1f4b468521d0ecabfb0731483a diff --git a/submodules/volto b/submodules/volto index b629e5acbc..6b493b4397 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit b629e5acbc2539f9ab1ef758fca4965eec9ffb44 +Subproject commit 6b493b4397bbf8f2b2f120ba442a64762caea761