diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 8beeb58c4..9ae0eeee5 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,7 +18,7 @@ build: # If there are no changes (git diff exits with 0) we force the command to return with 183. # This is a special exit code on Read the Docs that will cancel the build immediately. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/6.0 -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; then exit 183; fi diff --git a/coredev/agreement.md b/coredev/agreement.md deleted file mode 100644 index 337895245..000000000 --- a/coredev/agreement.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -myst: - html_meta: - "description": "Contributing to Plone" - "property=og:description": "Contributing to Plone" - "property=og:title": "Contributing to Plone" - "keywords": "Contributing, Plone" ---- - -(contributing-to-plone-label)= - -# Contributing to Plone - -There are many people and companies who rely on Plone on a day-to-day basis, so we must enforce some level of code quality control. - -Plone's source code is hosted in git repositories at , but only members of the developer team have commit rights. - -Sending in a contributors agreement does not guarantee your commit access to the repositories, but once you send it in we will always have it on file for when you are ready to contribute. - -We ask that before requesting core access you familiarize yourself a little with the community since they will help you get ramped up: - -- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat ` with a focus on getting to know the active developers a bit. - -- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints). - - There are plenty of opportunities to meet the community and start contributing through various coding sessions, either in person or on the web. - - You may even be able to get immediate core access at a conference if you are flexing your mad coding skills and the right people are attending. - -- Get your feet wet by contributing to the [collective](https://collective.github.io/). - Don't worry about getting it perfect or asking for help. - This way you get to know us and we improve our code together as a community. - -- **Patches:** Historically we encouraged people to submit patches to the ticket collector. - These tickets are usually ignored forever. - Technically, for us to accept your patch, you must sign the contributors agreement. - If you want to contribute fixes, please just sign the agreement and go through the standard GitHub pull request process described below until you feel comfortable to bypass review. - If the ticket is trivial, you do not need to sign a contributor's agreement. - -Once you have familiarized yourself with the community and you are excited to contribute to the core: - -- Sign the contributor agreement at , then either send by postal mail to the address provided, or scan and email it to . - This offers both copyright protection and ensures that the Plone Foundation is able to exercise some control over the codebase, ensuring it is not appropriated for someone's unethical purposes. - For questions about why the agreement is required, please see [About the Plone Contributor Agreement -](https://plone.org/foundation/contributors-agreement). - -If you aren't sure where to start or just want more direction, feel free to get in the forum or in chat, and ask for help. -While there is no official mentoring process, there are plenty of people willing to act in that role and guide you through the steps of getting involved in the community. -A common way to start contributing is to participate in a [Plone sprint](https://plone.org/news-and-events/events/sprints). - -**Welcome to the Plone community!** - - -## Dealing with pull requests on GitHub - -Before we can merge a pull request, we must ensure that the author has signed the Plone Contributor Agreement. - -If they're listed in either the [Developers](https://github.com/orgs/plone/teams/developers/members) or [Contributors](https://github.com/orgs/plone/teams/contributors/members) team, the author has signed the Plone Contributor Agreement, so we can go ahead and merge. - -If they aren't listed there, they may have signed and returned the Plone Contributor Agreement, but they were not yet added to a team. -You can ask agreements@plone.org to verify. - -Pull requests without a signed Plone Contributor Agreement can only be merged in trivial cases, and only by the release manager. diff --git a/coredev/continous-integration.md b/coredev/continous-integration.md deleted file mode 100644 index a1458cf41..000000000 --- a/coredev/continous-integration.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -myst: - html_meta: - "description": "Essential continuous integration practices" - "property=og:description": "Essential continuous integration practices" - "property=og:title": "Essential continuous integration practices" - "keywords": "Plone, continuous integration, best practices" ---- - -# Essential continuous integration practices - -The CI system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code. - -Build breakages are a normal and expected part of the development process. -Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential rules that needs to be followed in order to achieve a stable build. - - -## 1) Don't check in on a broken build - -Do not make things more complicated for the developer who is responsible for breaking the build. - -If the build breaks, the developer has to identify the cause of the breakage as soon as possible and should fix it. -If we adopt this strategy, we will always be in the best position to find out what caused the breakage and fix it immediately. -If one of the developers has made a check-in and broken the build as a result, we have the best chance of fixing the build if we have a clear look at the problem. -Checking in further changes and triggering new builds will just lead to more problems. - -If the build is broken over a longer period of time (more than a couple of hours) you should either notify the developer who is responsible for the breakage, fix the problem yourself, or just revert the commit in order to be able to continue to work. - -```note -There is one exception to this rule. -Sometimes there are changes or tests that depend on changes in other packages. -If this is the case, there is no way around breaking a single build for a certain period of time. -In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes. -``` - - -## 2) Always run all commit tests locally before committing - -Following this practice ensures the build stays green, and other developers can continue to work without breaking the first rule. - -There might be changes that have been checked in before your last update from the version control that might lead to a build failure in Jenkins in combination with your changes. -Therefore it is essential that you check out ({command}`git pull`) and run the tests again before you push your changes to GitHub. - -Furthermore, a common source of errors on check-in is to forget to add some files to the repository. - -If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system. - - -## 3) Wait for commit tests to pass before moving on - -Always monitor the build's progress, and fix the problem right away if it fails. -You have a far better chance of fixing the build, if you just introduced a regression than later. -Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours. - - -## 4) Never go home on a broken build - -Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially stops all other developers from working on it. -Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable. -It will prevent all the other developers to stop working on the build or fixing the errors that you introduced. - - -## 5) Always be prepared to revert to the previous revision - -In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision. - - -## 6) Time-box fixing before reverting - -When the build breaks on check-in, try to fix it for ten minutes. -If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system. -This way you will allow other developers to continue to work. - - -## 7) Don't comment out failing tests - -Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible. -While this impulse is understandable, it is **wrong**. - -The tests have been passing for a while and then start to fail. -This means that we either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason. - -You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). - - -## 8) Take responsibility for all breakages that result from your changes - -If you commit a change and all the tests you wrote pass, but others break, the build is still broken. -This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. -This means that you have introduced a regression bug into the application. - -It is **your responsibility**—because you made the change—to fix all tests that are not passing as a result of your changes. - -There are some tests in Plone that fail randomly, we are always working on fixing those. -If you think you hit such a test, try to fix it (better) or re-run the Jenkins job to see if it passes again. - -In any case the developer who made the commit is responsible to make it pass. - - -## Further Reading - -Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community. - -If you want to learn more about continuous integration and continuous delivery, I'd recommend that you buy this book. diff --git a/coredev/contributors_agreement_explained.md b/coredev/contributors_agreement_explained.md deleted file mode 100644 index 88851f6c8..000000000 --- a/coredev/contributors_agreement_explained.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -myst: - html_meta: - "description": "Contributor's Agreement for Plone explained" - "property=og:description": "Contributor's Agreement for Plone explained" - "property=og:title": "Contributor's Agreement for Plone explained" - "keywords": "Contributor, Agreement, Plone" ---- - -```{todo} -All this 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. -``` - -# Contributor's Agreement for Plone explained - -Prospective contributors to the Plone code base are required to sign a contributor's agreement, which assigns copyright in the code to the Plone Foundation, the non-profit organization which stewards the Plone code base. - -This document explains the purposes of this, along with questions and answers about what this means. - -The Plone Contributor's Agreement can be found at https://plone.org/foundation/contributors-agreement. - - -## About the Plone Contributor Agreement - -The Foundation feels that it benefits the community for a single organization to hold the rights to Plone. -Prior to the Foundation, the intellectual property of Plone was jointly held by individual developers and by Alan Runyan and Alexander Limi. - -The community members who formed the Foundation felt that having the Foundation hold these rights provides several benefits: - -1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious. -2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use. -3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone. - - -## Questions and answers - -What does the Contributor's Agreement cover? - -> This agreement is for the Plone core codebase only. -> The Plone core codebase is that code which lives in the Plone core version repositories, currently located at [https://github.com/plone]. -> Contributions to the "Collective", currently located at [https://github.com/collective] are not assigned to the Plone Foundation, and are made available under whatever license the project developers wish to use, although add-on products that import from GPLed Plone code are of course subject to the terms of the GPL, which requires derived works to be GPL licensed. - -What rights will I continue to have for my contributions? - -> Contributors are asked to transfer their intellectual property rights to the Foundation. -> In return, they will be given back irrevocable rights to use and distribute their contributions. -> They can even give their contributions to other Open Source projects (as long as those projects are compatible with the license Plone itself is issued under) or use them in non-Open Source commercial applications (if that is compatible with the license Plone is under). - -Do I have to sign the contributor's agreement to make changes to the Plone core codebase? - -> Yes. - -Do I have to sign the contributor's agreement to submit a patch to the Plone core codebase? - -> We enthusiastically welcome patches, but we can't merge them until you sign and return a contributor's agreement. -> (Unless, in the judgement of the Plone Release Manager, the patch is so tiny as not to constitute a "creative work". -> See the [Policy for Contributor Agreements and Patches] for more detail on this policy.) - -Can I grant the Plone foundation a non-exclusive license to my contributions rather than an exclusive license, so that I can contribute the same code to other projects under different terms or use the contribution for other commercial endeavors? - -> Not under the current version of the contributors agreement. - -Does the Foundation control use of the Plone trademark? - -> Yes. -> In order to keep the trademark, the Foundation (or any trademark owner) must demonstrate that they have acted to protect it. - -Will Plone always be available under an OSI-approved/Open Source license? -Couldn't the Board change its mind about this? - -> Plone will always be available under an OSI-approved license; this is written into the language of the contributor agreement each developer and the foundation sign. - -Will Plone ever be available under a non-GPL license? - -> The current Plone approach states that companies can negotiate a non-GPL license. -> Thus, the Foundation might pursue a dual-licensing (GPL and non-GPL) scheme - -> but, at this time, the Board has not yet created any policies on this. -> This is an important question for the community, of course, and the Foundation intends to have this conversation in a transparent way. - -Why would anyone want a non-GPL Plone? - -> Two possible reasons: some companies are reluctant to do in-house modifications of framework-like systems (such as Plone) that are under the GPL, fearing that a clause in the GPL might force them to disclose their internal work - thus wanting to license it under (for example) a BSD-style license. -> Second, companies may wish to offer a commercial version of Plone, under a conventional shrink-wrap license, without the obligation to reveal source code or share changes. - -How much would a non-GPL version of Plone cost? - -> Would a small company be able to afford one? -> Neither the Foundation nor the Board have made any decisions about a non-GPL version, let alone about pricing. -> However, one of the Foundation's stated goals is to maintain a level playing field for Plone while trying to benefit all of the Plone commons. -> If a non-GPL version was available, and a large company bought it, -> added features to it, and sold it, wouldn't they be using our work without an obligation to give back? -> It's helpful to remember the core value open source provides: distributed development, maintenance, security checking, and support. -> Companies that build large features for Plone are **already** having to make decisions of whether to release their products under an open source license or not (since they could always release them as a Product, not as a modification to the Plone core). -> Despite this, though, many large and excellent contributions—such as Archetypes—have been made, and the Foundation hopes that companies will continue to do so. -> In any event, a company that purchases a non-GPL license (should such ever become available) is contributing financial resources to our community, which can be used to further develop, market, and protect the GPL version of Plone. - -- https://plone.org/foundation/contributors-agreement/agreement.pdf -- https://github.com/collective -- https://github.com/plone -- [Policy for Contributor Agreements and patches](https://plone.org/foundation/materials/foundation-resolutions/patch-policy-052011) diff --git a/coredev/culture.md b/coredev/culture.md deleted file mode 100644 index 545b90996..000000000 --- a/coredev/culture.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone developer culture" - "property=og:description": "Plone developer culture" - "property=og:title": "Plone developer culture" - "keywords": "Plone, developer, culture" ---- - -```{todo} -This content is probably redundant and should be purged. -``` - -# Plone developer culture - -If you are going to contribute to Plone, we ask a couple things. -First, please join the [Plone forum](https://community.plone.org) and at minimum lurk around. -You will quickly see how people work and what kind of things are best suited for group discussion. -Second, please ask for help setting up your environment, in the forum. - -Most of our developers work there and you will get the best advice there. - -If you are actively committing code, always keep an eye on our [Jenkins CI](https://jenkins.plone.org/) to know if your recent commits have broken (or fixed!) the build. - -If you are in a timezone when things are not very active, please post to the forum or grab a drink and wait for people to wake up. - -**When in doubt, please ask** - -The code base is very complicated and everyone is vested in the right thing happening. -Despite the occasional grouch here and there, most Plone developers will go out of their way to get you on the right path. diff --git a/coredev/getting-started-with-development.md b/coredev/getting-started-with-development.md deleted file mode 100644 index 5975adc21..000000000 --- a/coredev/getting-started-with-development.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -myst: - html_meta: - "description": "Getting started with Plone development" - "property=og:description": "Getting started with Plone development" - "property=og:title": "Getting started with Plone development" - "keywords": "Plone, development" ---- - -# Getting started with development - -This document assumes you want to run the current latest Plone source, fix a bug in Plone, or test an add-on in the context of the latest code, and will detail the full process. -For how to write Plone Improvement Proposals (PLIPs), read {doc}`plips`. - - -## Version support policy - -If you are triaging or fixing bugs, keep in mind that Plone has a [version support policy](https://plone.org/download/release-schedule#91815aec-0513-40e0-a804-55ea787a8c68). - - -## Dependencies - -- git. See [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). -- [Python](https://python.org/). See the [current supported versions of Python](https://plone.org/download/release-schedule). -- If you are on macOS, you will need to install [XCode](https://developer.apple.com/xcode/). - You can do this through the App Store or registering through the Apple Developer Program. -- [Pillow](https://pypi.org/project/Pillow/). -- [GCC](https://gcc.gnu.org/) in order to compile ZODB, Zope and lxml. -- [libxml2 and libxslt](https://gitlab.gnome.org/GNOME/libxslt/-/releases), including development headers. - - -(setup-development-environment)= - -## Set up your development environment - -The first step in fixing a bug is getting this [buildout](https://github.com/plone/buildout.coredev) running. -We recommend fixing the bug on the latest branch, and then [backporting](https://en.wikipedia.org/wiki/Backporting) as necessary. -Dependent on the current development cycle, there may exist a future branch. -For example, `6.0` is the actively maintained stable branch. -[Some other branch] is the future, currently unstable, active development branch. -More information on switching release branches is described below. - -To set up a plone 6 development environment. - -```shell -cd ~/projects # or wherever you want to put things -git clone -b 6.0 https://github.com/plone/buildout.coredev ./plone6devel -cd ./plone6devel -./bootstrap.sh -``` - -If you run into issues in this process, please see {doc}`troubleshooting`. - -This will run for a long time if it is your first pull (approximately 20 minutes). -Once that is done pulling down eggs, you can start your new instance with: - -```shell -./bin/instance fg -``` - -or as a WSGI service with: - -```shell -./bin/wsgi -``` - -To login, the defaults are: - -- username: admin -- password: admin - - -## Switching branches - -If your bug is specific to one branch, or you think it should be backported, you can switch branches. -The first time you get a branch, you must do: - -```shell -git checkout -t origin/6.0 -``` - -This should set up a local 6.0 branch tracking the one on GitHub. -From then on you can just do: - -```shell -git checkout 6.0 -``` - -To see what branch you are currently on: - -```shell -git branch -``` - -The line with a `*` by it will indicate the branch on which you are currently working. - -```{important} -Make sure to rerun buildout if you were in a different branch earlier to get the correct versions of packages, otherwise you will get some weird behavior. -``` - - -## Jenkins and mr.roboto - -Plone has a continuous integration (CI) setup and follows CI rules. - -When you push a change to any Plone package, our testing/CI middleware `mr.roboto` starts running all the tests that are needed to make sure that you don't break anything. -For each Plone and Python version we run two jobs, one for the package itself (which will give you a fast feedback, within 10 minutes) and one on the full `coredev` build (which can take up to an hour, but makes sure no other packages are effected by your change. - -For more information you can read {doc}`Mr. Roboto workflow ` or our [Jenkins machine](https://jenkins.plone.org/). - -The CI system at `jenkins.plone.org` is a shared resource for Plone developers to notify them of regressions in Plone code. -Build breakages are a normal and expected part of the development process. -Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors. -Though, there are some essential practices that need to be followed in order to achieve a stable build: - -1. Don't check in on a broken build. Check Jenkins first. -2. Always run all commit tests locally before committing. -3. Wait for commit tests to pass before moving on. -4. Never go home on a broken build. -5. Always be prepared to revert to the previous revision. -6. Time-box fixing before reverting. -7. Don't comment out failing tests. -8. Take responsibility for all breakages that result from your changes. - -See {doc}`continous-integration` for more information. - -Since it can be burdensome to check this manually, install the tools locally to always see the current state of the Plone CI Server: - -- For Linux and X11 environments, there is [BuildNotify](https://pypi.org/project/BuildNotify/). -- For macOS there is [CCMenu](http://ccmenu.org/). -- For windows there is [CCTray](https://cruisecontrolnet.org/cctray_download_plugin-2/). -- For Firefox there is [CruiseControl Monitor](https://addons.thunderbird.net/EN-US/firefox/addon/cruisecontrol-monitor/?src=cb-dl-name) (no longer supported), and many other [Jenkins plugins](https://addons.mozilla.org/en-US/firefox/search/?q=jenkins). - -These tools were built to parse a specific file that CruiseControl, another CI tool, generated. -Jenkins generates this file too. -You can configure your notifier of choice with this url: `https://jenkins.plone.org/cc.xml` [which is a 404, LOL!] - - -## Check out packages to fix - -Most packages are not in {file}`src/` by default, so you can use `mr.developer` to get the latest and make sure you are always up to date. -It can be a little daunting at first to find out which packages cause the bug in question, but just ask in https://community.plone.org/ if you need some help. -Once you know which packages you want, pull their source. - -You can get the source of the package with `mr.developer` and the checkout command, or you can go directly to editing {file}`checkouts.cfg`. -We recommend the latter but will describe both. -In the end, {file}`checkouts.cfg` must be configured, so you might as well start there. - -At the base of your buildout, open {file}`checkouts.cfg` and add your package if it's not already there: - -```cfg -auto-checkout = - # my modified packages - plone.app.caching - plone.caching - # others - ... -``` - -Then rerun buildout to get the source packages: - -```shell -./bin/buildout -``` - -Alternatively, we can manage checkouts from the command line, by using `mr.developer`'s `bin/develop` command to get the latest source. -For example, if the issue is in `plone.app.caching` and `plone.caching`: - -```shell -./bin/develop co plone.app.caching -./bin/develop co plone.caching -./bin/buildout -``` - -Don't forget to rerun buildout! -In both methods, `mr.developer` will download the source from GitHub (or otherwise) and put the package in the {file}`src/` directory. -You can repeat this process with as many or as few packages as you need. -For some more tips on working with `mr.developer`, please read {doc}`mrdeveloper`. - - -## Testing Locally - -To run a test for the specific module you modify: - -```shell -./bin/test -m plone.app.caching -``` - -These should all run without error. -Please don't check in anything that doesn't succeed! -Now write a test case for the bug you are fixing, and make sure everything is running as it should. - -After the module level tests run with your change, please make sure other modules aren't affected by the change by running the full suite, including robot-tests (remove the `--all` to run without robot tests): - -```shell -./bin/test --all -``` - -```{note} -Tests take a long time to run. -Once you become a master of bugfixes, -you may just let jenkins do this part for you. -More on that below. -``` - - -## Updating `CHANGES.rst` and `checkouts.cfg` - -Once all the tests are running locally on your machine, you are **ALMOST** ready to commit the changes. -You must perform a couple housekeeping chores before moving on. - -First, edit {file}`CHANGES.rst` (or {file}`CHANGES.txt`, or {file}`HISTORY.txt`) in each package you have modified and add a summary of the change. -This change note will be collated for the next Plone release and is important for integrators and developers to be able to see what they will get if they upgrade. -New changelog entries should be added at the very top of {file}`CHANGES.rst`. -Some packages already switched to use [towncrier](https://pypi.org/project/towncrier/). -If this is the case you'll find a note at the top of the `CHANGES.rst` file. - -Most importantly, if you didn't do it earlier, edit the file {file}`checkouts.cfg` in the buildout directory, and add your changes package to the `auto-checkout` list. -This lets the release manager know that the package has been updated, so that when the next release of Plone is cut, a new egg will be released, and Plone will need to pin to the next version of that package. -In other words, this is how your fix becomes an egg! - -Note that there is a section separator called "# Test Fixes Only". -Make sure your egg is above that line, else your egg probably won't get made very quickly. -This just tells the release manager that any eggs below this line have tests that are updated, but no code changes. - -Modifying the file {file}`checkouts.cfg` also triggers the buildbot, [jenkins](https://jenkins.plone.org/), to pull in the egg and run all the tests against the changes you just made. -Not that you would ever skip running all tests. - -If your bug is in more than one release, for example 5.2 and 6.0, please checkout both branches, and add it to the file {file}`checkouts.cfg`. - - -## Commits and pull requests - -Review the following checklist: - -- Did you fix the original bug? -- Is your code consistent with our [Style Guides](https://5.docs.plone.org/develop/styleguide/index.html)? -- Did you remove any extra code and lingering pdbs? -- Did you write a test case for that bug? -- DO all test cases for the modules and Plone pass? -- Did you update {file}`CHANGES.rst` in each packages you touched? -- Did you add your changed packages to {file}`checkouts.cfg`? - -If you answered *YES* to all of these questions, then you are ready to push your changes! -A couple quick reminders: - -- Only commit directly to the development branch if you're confident that your code won't break anything badly and the changes are small and fairly trivial. - Otherwise, please create a `pull request` (more on that below). -- Please try to make one change per commit. - If you are fixing three bugs, make three commits. - That way, it is easier to see what was done when, and easier to roll back any changes if necessary. - If you want to make large changes cleaning up whitespace or renaming variables, it is especially important to do so in a separate commit for this reason. -- We have a few angels that follow the changes and each commit to see what happens to their favourite CMS! - If you commit something REALLY sketchy, they will politely contact you, most likely after immediately reverting changes. - There are no official people assigned to this so if you are especially nervous, ask in https://community.plone.org/. - - -## Commit to `Products.CMFPlone` - -If you are working a bug fix on `Products.CMFPlone`, there are a couple other things to take notice of. -First and foremost, you'll see that there are several branches. -At the time of writing this document, there are branches for 4.2.x, 4.3.x and master, which is the implied 5.0. -This may change faster than this documentation, so check the branch dropdown on GitHub. - -If the fix is only for one version, make sure to get that branch. -However, chances are the bug is in multiple branches. - -Let's say the bug starts in 4.1. -Pull the 4.1 branch and fix and commit there with tests. - -If your fix only involved a single commit, you can use git's `cherry-pick` command to apply the same commit to a different branch. - -First check out the branch: - -```shell -git checkout 4.2 -``` - -And then cherry-pick the commit (you can get the SHA hash from git log): - -```shell -git cherry-pick b6ff4309 -``` - -There may be conflicts. -If so, resolve them, then follow the directions git gives you to complete the cherry-pick. - -If your fix involved multiple commits, cherry-picking them one by one can get tedious. -In this case, things are easiest if you did your fix in a separate feature branch. - -In that scenario, you first merge the feature branch to the 4.1 branch: - -```shell -git checkout 4.1 -git merge my-awesome-feature -``` - -Then return to the feature branch, and make a branch for rebasing it onto the 4.2 branch: - -```shell -git checkout my-awesome-feature -git checkout -b my-awesome-feature-4.2 -git rebase ef978a --onto 4.2 -``` - -(`ef978a` happens to be the last commit in the feature branch's history before it was branched off of 4.1. -You can look at `git log` to find this.) - -At this point, the feature branch's history has been updated, but it hasn't actually been merged to 4.2 yet. -This lets you deal with resolving conflicts before you actually merge it to the 4.2 release branch. -Let's do that now: - -```shell -git checkout 4.2 -git merge my-awesome-feature-4.2 -``` - -### Branches and forks and direct commits - oh my! - -```{note} -This section needs a rewrite. -Meanwhile we do not allow direct commits, except in very rare cases. -``` - -Plone used to be in an svn repository, so everyone is familiar and accustomed to committing directly to the branches. -After the migration to GitHub, the community decided to maintain this spirit. -If you have signed the [contributor agreement](https://plone.org/foundation/contributors-agreement), you can commit directly to the branch. -For Plone, this would be the version branch, whereas for most other packages this would be `main`. - -HOWEVER, there are a few situations where a branch is appropriate. -If you: - -- are just getting started -- are not sure about your changes -- want feedback or code review -- are implementing a non-trivial change - -then you should create a branch of whatever packages you are using, and then use the [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) feature of GitHub to get review. -Everything about this process would be the same except you need to work on a branch. -Take the `plone.app.caching` example. -After checking it out with `mr.developer`, create your own branch with: - -```shell -cd src/plone.app.caching -git checkout -b my_descriptive_branch_name -``` - -```{note} -Branching or forking is your choice. -I prefer branching, and I'm writing the docs so this uses the branch method. -If you branch, it helps us because we *know* that you have committer rights. -Either way it's your call. -``` - -Proceed as normal. -When you are ready to push your fix, push to a remote branch with: - -```shell -git push origin my_descriptive_branch_name -``` - -This will make a remote branch in GitHub. -Navigate to this branch in the GitHub user interface, and on the top right, there will be a button that says {guilabel}`Pull Request`. -This will turn your request into a pull request on the main branch. -There are people who look once a week or more for pending pull requests and will confirm whether or not it's a good fix, and give you feedback where necessary. -The reviewers are informal and very nice, so don't worry. -They are there to help! -If you want immediate feedback, visit https://community.plone.org/ with the pull request link and ask for a review. - -```{note} -You still need to update the file {file}`checkouts.cfg` in the correct branches of `buildout.coredev`! -``` - - -## Finalize issues - -If you are working from an issue, please don't forget to go back to the issue, and add a link to the change set. -We don't have integration with GitHub yet so it's a nice way to track changes. -It also lets the reporter know that you care. -If the bug is really bad, consider pinging the release manager and asking them to make a release. - - -## FAQ - -How do I know when my package got made? -: You can follow the project on GitHub, and watch its [timeline](https://github.com/orgs/plone/dashboard). - You can also check the {file}`CHANGES.rst` of every plone release for a comprehensive list of all changes, and validate that yours is present. diff --git a/coredev/git.md b/coredev/git.md deleted file mode 100644 index 9c9034f75..000000000 --- a/coredev/git.md +++ /dev/null @@ -1,642 +0,0 @@ ---- -myst: - html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "keywords": "" ---- - -```{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. -``` - -# Working with Git and GitHub - -## The Plone Git workflow and branching model - -Our repository on GitHub has the following layout: - -- **feature branches**: - All development for new features must be done in dedicated branches, normally one branch per feature. -- **main** or **master** **branch**: - when features get completed they are merged into the master branch; bugfixes are commited directly on the master branch, -- **tags**: - whenever we create a new release, we tag the repository so we can later retrace our steps, or rerelease versions. - - -## Git basics - -Some introductory definitions and concepts, if you are already familiar enough with Git, head to next section: {ref}`general-guidelines-label`. - - -### Mental working model - -With Git (as well as all modern [DVCS](http://en.wikipedia.org/wiki/Distributed_revision_control)), distributing changes to others is a two steps process (contrary to traditional VCS like `svn`). - -This way what on svn is a single `svn ci` in Git is two commands: `git commit` and `git push`. - -This may seem to be a drawback, but instead it's a feature. - -**You are working locally until you decide to push your changes.** - -Not a single commit anymore, but a series of them, meaning that all those fears, concerns, doubts are taken away! - -You can freely fix/change/remove/rework/update/... your commits afterwards. - -Push your changes whenever you are sure they are what you, and others, expect them to be. - - -### Concepts - -In Git there are: - -commits - -: A patch made out of changes (additions, removals) on files tracked by Git. - -branches - -: Series of commits that have a name. - -tags - -: A name attached to a single commit. - -`HEAD` - -: A pointer that always tells you where you are (extremely useful when doing some operations). - -The index - -: A temporal staging storage with changes on files that are pending to be added to a commit. - If your Git output is colored, green filenames are those in the index. - -Working tree - -: Your current modified files. - This is the only place where you can loose your changes. - If your Git output is colored, red filenames are those in the working tree. - -Stash - -: Temporal storage for changes, again, extremely useful in some scenarios, see further below for examples. - -### Branches - -Another great feature of DVCS is cheap branching, i.e. branching in Git is effortless and really useful. -As it's no longer too much effort to branch, there is no need to always work on the master branch. - -A developer can branch easily for each fix/feature. - -Branches allow you to tinker with your changes while keeping the master branch clean. - -Not only that, it also allows you to keep modifying your changes until you and your peers are fine with them. - -Further documentation: -[Introduction to branching](http://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell). - -### Commands - -Some of the most useful/common commands (note that most of them have switches that enhance/*completely twist* their functionality): - -Just append `--help` on all of them to get their full definitions and options, -i.e. `git add --help`. - -clone - -: Download a repository from a given remote URL. - -add - -: Add the given files to the index. - - ```{note} - **pro tip**: once a file is add via `git add` your changes will never be lost! - As long as you don't remove the `.git` folder, even if you remove the file you just added, the changes you made before doing `git add` are still there ready to be recovered at any time! - ``` - -status - -: Get an overview of the repository status. - - If there are files on the index, or files not tracked by Git, or the status of your local branch with regards to the remote, etc. - -diff - -: See the current changes made to the files already tracked by Git. - - ```note} - Fear not, if you used `git add SOME_FILE` and then `git diff` doesn't output anything you haven't lost your changes! - - Just try `git diff --cached`. - Now you know how to see the working tree changes (`git diff`) and index changes (`git diff --cached`). - ``` - -commit - -: Create/record changes to the repository (locally only, nothing is sent over the wire). - -push - -: Send your changes, - either commits or a complete new branch, - to the configured remote repository. - -show - -: Display the given commit(s) details. - -log - -: Shows the repository history. - Sorted by date (last commit at the top), - and like all other commands, - extremely versatile with all its switches. - - See further below for an example of a powerful combination of switches. - -branch - -: Create a branch. - -fetch - -: Download changes from the remote repository. - - **Without** changing the current `HEAD` (see rebase and pull commands). - -pull - -: Fetch and integrate changes from remote repository. - - Internally that means to do a `git fetch` plus either `git merge` or `git rebase`. - - :::{note} - Used careless most probably adds extra superfluous commits. - See further down. - ::: - -merge - -: Join two, - or more, - branches together. - -rebase - -: Forward-port your current local commits (or branch) to be based on top of another commit. - - An image is worth 1000 words: - -checkout - -: Change to the given branch or get the given file to its latest committed version. - - :::{note} - If Git is criticized for being complex, - this command is one of the main sources of complains. - - You can compare it with `svn switch` if you happen to know it. - - Fear not though, - two main use cases are: - change branches and reset a file to its last committed version. - Still, - the syntax for both cases is really simple. - ::: - -cherry-pick - -: Apply a commit(s) to the current working branch. - -stash - -: Use a temporal storage to save/restore current changes still not meant to be used on a commit. - - :::{note} - Seems a bit not so useful on a first look, - but it is indeed. - - Think about this scenario: - you are working on your branch coding away. - All of the sudden you notice a small fix that should be done directly on master. - Thanks to `git stash` you can save your changes quickly and safely, - move to master branch, - do the quick fix, - commit and push it, - move back to your branch and `git stash pop` to recover your changes and continue hacking away. - ::: - -reflog - -: When things go bad you will **love** this command. - - It effectively shows you a histogram of what happened on the repository, - allowing you to rollback you repository to a previous stage. - - Extremely useful once a bad interactive rebase has happened. - -(general-guidelines-label)= - -## General guidelines - -### Pulling code - -Let's compare this two histories: - -``` -* 3333333 (HEAD, master) Merge branch 'feature-branch' into master -|\ -| * 2222222 (feature-branch) Last changes on feature-branch -| * 1111111 Merge branch 'master' into feature-branch -| |\ -| * | 0000000 More changes on feature branch -| * | fffffff Merge branch 'master' into feature-branch -| |\ \ -* | | | eeeeeee master keeps rocking -| |_|/ -|/| | -* | | ddddddd master goes and goes -| |/ -|/| -* | ccccccc master evolves -| * bbbbbbb First commit on feature-branch -|/ -* aaaaaaa commit on master # this is where feature-branch was created -``` - -With: - -``` -* 3333333 (HEAD, master) Merge branch 'feature-branch' into master -|\ -| * 2222221 (feature-branch) Last changes on feature-branch -| * 0000001 More changes on feature branch -| * bbbbbb1 First commit on feature-branch -|/ -* eeeeeee master keeps rocking -* ddddddd master goes and goes -* ccccccc master evolves -* aaaaaaa commit on master -``` - -What do we see above? Actually and contrary to what it seems, -exactly the same **result** -(as how the files and its content look like on commit `333333`). - -The second version is far more easy to understand what happened and removes two superfluous commits -(the two partial merges with master (`fffffff` and `1111111`). - -This happens if you have not properly configured `git pull`. -By default it does a `merge` meaning that an extra commit is always added, -tangling the history and making this more complex when looking back for what happened there. - -#### How to solve it? - -*ALWAYS* do a {command}`git pull --rebase` when fetching new code, -configure Git to do always so with: - -``` -git config branch.autosetuprebase always # add the --global switch to make it default everywhere -``` - -This way you do not introduce new extra commits and the Git history is kept as simple as possible. - -This is especially important when trying to understand why some changes were made, -or who did actually change that line, -etc. - -A couple of further explanations: - - - - -Search for `git merge vs rebase`, you will find plenty of literature. - -### Reviewing your changes - -After hacking for some minutes/hours/days you are finished and about to commit your changes, -great! - -*BUT*, -please, -do so with {command}`git add --patch`. - -The `--patch` (also `-p`) switch allows you to select which hunks you want to add on a commit. - -This is not only great to split changes into different commits, -but is also the time when you actually **review** your code before anyone else sees it. - -This is the time when you spot typos, pep8 errors, misaligned code, lack of docstrings in methods, -that a permission is not defined on Generic Setup, that an upgrade should be needed... - -Remember that the first code review is the one you do on your own. -Some inspiration/better phrasing: - - -And please, do remember the gold metric about reviewing code: - - -#### One commit does one thing - -Repeat with me: *One commit does one thing*. Period. - -When someone else needs to review your code, most probably she will give up or just skim over your code -if there are too many (unrelated) changes. - -Reviewing commits with +20 files doing all sorts of changes on them (maybe even unrelated) -is no fun and adds complexity and [cognitive load](http://en.wikipedia.org/wiki/Cognitive_load). - -Something that should mostly be a verification of a checklist like: - -- the browser view is registered on ZCML? - -- is there an interface for that form? - -- the pt and py are there? - -- ... - -Turns instead into a list of questions: - -- why is this interface renamed here if it has nothing to do with this adapter? -- all this removal of deprecated code while adding new features just mixes the diff, - am I missing something? -- *others* - -If you can not express what has been changed within 50 characters (suggested length of a commit message subject), -or you say it like "it does XXX and YYY", you most probably need to split that commit into, at least, -two or more commits. - -That doesn't mean that a +20 files or +100 lines of code changes are bad per se, you may be doing -a simple refactoring across lots of files, that's fine and good actually. - -As long as a commit is just and only about a specific purpose, and not a mixed selection of the following: - -- refactoring code -- moving things around -- fixing some bugs while at it -- adding some docs -- a new cool feature -- fixing typos on documentation -- pep8 fixes - -It is absolutely fine to refactor. - -And this is actually to help both your present self and your +5 years from now that will have to refactor that code of yours, -and maybe is struggling to understand what was going on there. - -Following this advice will: - -- keep things simple where there's no gain in adding complexity -- make your changes easy to be reviewed -- make later on lookups on those changes easy to follow - -### Making commits - -For commit messages see: {ref}`git_commit_message_style_guide`. - -#### Adding references to issues - -Always add the full URL to the issue/pull request you are fixing/referring to. - -Maybe within the Git repository it makes sense, but as soon as you are outside of it, it will not. - -Take into account mr.roboto automatic commits to buildout.coredev for example, if your commit message goes like *Fix for #33*, -which issue/pull request is that fixing? - -The one in buildout.coredev itself? On another issue tracker? Somewhere else? - -It would be far better if the commit goes instead like: - -``` -Brief description - -Further explanation. - -Fixes: https://github.com/plone/plone.app.discussion/issue/999 -``` - -#### Bad examples - -Some bad examples of commit messages: - - -Commit messages goes like *"Make note about how this interface is now for BBB only"*. - -Question: if it's BBB only, where is the new place to look for that interface now? - -The problem is that, in this case Martin, wrote that in 2009, so most probably once a refactor of that package -is done later on 2015, Martin is no longer around, and if he was, most probably he would not remember something from +6 years ago. - -Ask yourself a question: - -If someone comes to you asking details about a random commit done by you +5 years ago, what will you reply? - -Try that, get one project that you worked 5 years ago, get a random commit and: - -See if, just by reading the commit message, you are given enough information of what changes have been made, -when comparing the commit message and the actual code. -Does the commit message match the code changed? - -### Before pushing commits - -Code is reviewed, spread into nice isolated commits, descriptive enough commit messages are written, *what's left?* - -A final overview of what you are about to push. - -To do so, you can get an idea with the following Git alias (to be added on your `~/.gitconfig`): - -``` -[alias] - fulllog = log --graph --decorate --pretty=oneline --abbrev-commit --all -``` - -Now run {command}`git fulllog` on your Git repository, you will see a nice graph showing you the current situation. - -Maybe it makes you realize that commits need to be reordered, commit messages could get some improvements, -that you forgot to add a reference to an issue, ... - -## Pull requests - -Some specific tips and best practices for pull requests. - -### Always rebase - -Always rebase on top of the branch you want your changes to be merged before sending a pull request, -and as your pull request is still pending to be merged and the master branch evolves, keep rebasing it. - -To do so: - -``` -git checkout -git rebase master # or the branch you are targeting to integrate your changes to -# done! -# or if there are conflicts, -# fix them and follow instructions from git itself -``` - -The principle is, if you do merges with master, you are actually spreading your pull request into more commits, -and at the end making it more difficult to track what was changed. - -On top of that, the commit history is more complex to follow. - -See the history example above: {ref}`general-guidelines-label`. - -Unfortunately the flat view from GitHub prevents us from seeing that, -which is a shame. - -### One line one commit - -On a series of commits make sure the same code line is not changed twice, -the worst thing you can do to the one reviewing your changes, -is to make him/her spend time reviewing some code changes that one the next commit are changed again to do something else. - -It will not only make your commits smaller, but it will also make it easy to do atomic commits. - -### No cleanup commits please - -*On the context of a pull request* - -Ask yourself: What relation does a cleanup commit, say pep8 fixes or other code analysis fixes, -have with your pull request? - -Couldn't that pep8 fixes commit or small refactoring go straight into master branch? - -Or even if you send a pull request for it, chances are that it will be merged right away. -As long as it is a cleanup commit, there's not much to argue with it. - -The same goes with commits that improve or actually fix previous commits (within the same pull request). -A series of commits like this: - -``` -* 11ba28c Last fix, finally -* 11ba28c Fix tests, again -* 11ba28c Fix tests -* 11ba28c Do something fancy -* 11ba28c Failing test, we are doing TDD right? -``` - -Only tells you that the author did not take care at all about the one who will review it, -and specially about the person that in +5 years will try to understand that test. -Specially because now the test is not only spread between 4 commits, but most probably during those 5 years -it has already been refactored, maybe a {command}`git blame` will report that within that test method, -there are +5 related current commits to check, not nice right? - -#### Squashing commits - -To fix the previous example, run the following command: - -``` -git rebase ---interactive # which mostly is usually master -``` - -This allows you to rewrite the story of your branch. -See a more [elaborate description with examples](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase-i/). - -:::{note} -Be careful on not to run that on master itself! -Please take your time to really understand it. - -It's a really powerful tool, -and as [Stan Lee says](http://en.wikiquote.org/wiki/Stan_Lee), -it comes with great responsibility. -::: - -To actually make it easier you can do commits like this: - -``` -git commit --fixup HASH -``` - -Where `HASH` is the commit hash you want the changes you are about to commit be merged with. - -This way, when running {command}`git rebase --interactive`, Git will already reorder the commits as you already want. - -### No side changes - -That's an extension to the previous point. - -Keeping pull requests simple and to the point, without changes not related to the pull request itself, -will make your changes easier to understand and easier to follow. - -Again this applies: - - -### The review-change-push-review cycle - -After you have made a pull request, -you should ask for a review via the GitHub interface. - -After the review you will frequently have to do some changes of your PR, -perhaps add a missing changelog entry, and so on. - -When the changes are done, rebase your branch again -and squash any fixup-commits, all as described above. - -Finally you should force push your feature branch to GitHub. -Only force push on your own feature branches! -Never on branches shared with other people. - -After the update of your branch, -the GitHub PR interface will pick up the changes, -ready for returning to the reviewer, -and hopefully get a final go for the merge. - -## Recipes - -Assorted list of tips and tricks. - -### Change branches with uncommitted changes - -**Situation:** you are working on a pull request and while working on it founds that some cleanups are needed, -how to proceed forward? - -**Solution:** `git stash` or `git commit --amend -m"TMP"`. - -The basic idea here is: store your current changes safely (either on a Git stash commit or directly on a commit on the branch, -whichever you prefer), move to the canonical branch (`master` usually), do the fixes/cleanups/refactorings there, -commit those changes, rebase your branch on top of the changes you made, hack away. - -Command line version: - -``` -git stash # or git commit --amend -m"TMP" -git checkout master # or whatever happens to be the canonical branch name (i.e. 5.0 on buildout.coredev) -# do the cleanups && push them -git checkout your-branch # get back to your branch -git rebase master # again the canonical branch where you made the changes -git stash pop # or git reset HEAD^ if you did a git commit --amend -m"TMP" -# if needed, fix the conflicts, with patience and practise that's a piece of cake once you are used to -``` - -### Git visual applications - -Not everyone is a fan of the command line, for them there is a list of GUI clients on the official Git website: - - - -### Enhanced Git prompt - -Do one (or more) of the following: - -- -- -- - -### Git dotfiles - -Plone developers have dotfiles similar to these: -. - -## Learn more - -What's here is just the tip of the iceberg, there's plenty of Git knowledge on the web. - -A few good further resources are listed here (contributions welcome): - -- official online Git book: [Pro Git](http://git-scm.com/book/en/v2) -- PyCon 2015 talk: [Advanced Git by David Baumgold](https://www.youtube.com/watch?v=4EOZvow1mk4) diff --git a/coredev/guidelines.md b/coredev/guidelines.md deleted file mode 100644 index 6c9ea0236..000000000 --- a/coredev/guidelines.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -myst: - html_meta: - "description": "" - "property=og:description": "" - "property=og:title": "" - "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. -``` - -% Note: this page is linked to from CONTRIBUTING.rst in all packages. Keep it short! - -# Guidelines for contributing to Plone Core - -You probably came here by clicking one of the 'guidelines for contributing' links on GitHub. -You probably have an issue to report or you want to create a pull request. -Thanks a lot! -Let's bring you up to speed with the minimum you need to know to start contributing. - -## Create an issue - -- If you know the issue is for a specific package, you can add an issue there. - When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plone/Products.CMFPlone/issues). - -- Please specify a few things: - - - What steps reproduce the problem? - - What do you expect when you do that? - - What happens instead? - - Which Plone version are you using? - -- If it is a visual issue, can you add a screen shot? - -- If there is an error in the Site Setup error log, please include it. - Especially a traceback is helpful. - Click on the 'Display traceback as text' link if you see it in the error log. - - -## Create a pull request - -- Legally, you can NOT contribute code unless you have signed the {doc}`contributor agreement `. - This means that we can NOT accept pull requests from you unless this is done, so please don't put the code reviewers at risk and do it anyways. -- Add a changelog entry as file in the news directory. - For helpful instructions, please see: -- For new features, an addition to README.rst is probably needed. - A package may include other documentation that needs updating. -- All text that can be shown in a browser must be translatable. - Please mark all such strings as translatable. -- Be nice and use code quality checkers like flake8 and jshint. -- See if you can use git to squash multiple commits into one where this makes sense. - If you are not comfortable with git, never mind. -- If after reading this you become hesitant: don't worry. - You can always create a pull request, mark it as WIP (work in progress), and improve the above points later. diff --git a/coredev/index.md b/coredev/index.md deleted file mode 100644 index 80eb9b613..000000000 --- a/coredev/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -myst: - html_meta: - "description": "Development in Plone" - "property=og:description": "Development in Plone" - "property=og:title": "Development in Plone" - "keywords": "Developing, Plone, Contributing" ---- - -# Development in Plone - -This part describes the process of development in Plone. -It is primarily a technical resource for setting up your development environment, fixing bugs, and writing Plone Improvement Proposals (PLIPs). - - -## Plone Contributor Agreement - -You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). - -We can **NOT** accept pull requests from you until you have signed and returned the Contributor Agreement, and been approved. -Please don't put the code reviewers at risk by ignoring this requirement. - - -## Contents - -```{toctree} -:maxdepth: 2 - -guidelines -agreement -culture -getting-started-with-development -documentation -plips -issues -release -git -package-dependencies -``` - - -## Additional material - -These are some documents used as reference for this documentation. - -```{toctree} -:maxdepth: 1 - -contributors-agreement-explained -continous-integration -roboto -mrdeveloper -plip-review -``` - -```{todo} -The style guides are ancient and need to be overhauled. -``` - -Documenation's style is guided by Vale and the Microsoft Style Guide. -See [Contributing to Documentation](https://6.docs.plone.org/contributing/index.html). - -Our coding style guides are located at the [Plone Style Guide](https://5.docs.plone.org/develop/styleguide/index.html section. diff --git a/coredev/mrdeveloper.md b/coredev/mrdeveloper.md deleted file mode 100644 index 83d90a553..000000000 --- a/coredev/mrdeveloper.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -myst: - html_meta: - "description": "mr.developer" - "property=og:description": "mr.developer" - "property=og:title": "mr.developer" - "keywords": "mr.developer" ---- - -# `mr.developer` - -This buildout uses `mr.developer` to manage package development. -See https://pypi.org/project/mr.developer/ for more information, or run `bin/develop help` for a list of available commands. - -The most common workflow to get all the latest updates is: - -```shell -git pull -bin/develop rb -``` - -This will get you the latest `coredev` configuration, checkout and update all packages via git and Subversion in src, and run buildout to configure the whole thing. - -From time to time you can check if some old cruft has accumulated: - -```shell -bin/develop st -``` - -If this prints any lines with a question mark in front, you can cleanup by: - -```shell -bin/develop purge -``` - -This will remove packages from {file}`src/` which are no longer needed, as they have been replaced by proper egg releases of these packages. diff --git a/coredev/plip-review.md b/coredev/plip-review.md deleted file mode 100644 index 78aed655a..000000000 --- a/coredev/plip-review.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -myst: - html_meta: - "description": "PLIP review" - "property=og:description": "PLIP review" - "property=og:title": "PLIP review" - "keywords": "PLIP, review, Plone Improvement Proposal, Plone" ---- - -# PLIP review - -A Plone Improvement Proposal (PLIP) is a formal process to propose a change to improve Plone. - - -## Expectations - -A good PLIP review takes about four hours. -Please plan accordingly. -When you are done, if you have access to core, commit the review to the `plips` folder, and reference the PLIP in your commit message. -If you do not have access, attach your review to the PLIP ticket itself. - - -## Setting up the environment - -Follow the instructions in {doc}`getting-started-with-development`. -You will need to checkout the branch to which the PLIP is assigned. -Instead of running the buildout with the default buildout file, you will run the configuration specific to that PLIP: - -```shell -./bin/buildout -c plips/plipXXXX.cfg -``` - - -## Functionality review - -This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. - - -### General - -- Does the PLIP actually do what the implementers proposed? - Are there incomplete variations? -- Were there any errors running buildout? - Did the migration(s) work? -- Do error and status messages make sense? - Are they properly internationalized? -- Are there any performance considerations? - Has the implementer addressed them, if so? - - -### Bugs - -- Are there any bugs? - Nothing is too big nor small. -- Do fields handle wacky data? - How about strings in date fields, or nulls in required? -- Is validation up to snuff and sensical? - Is it too restrictive or not restrictive enough? - - -### Usability Issues - -- Is the implementation usable? -- How will novice end users respond to the change? -- Does this PLIP need a usability review? - If you think this PLIP needs a usability review, change the state to "please review" and add a note in the comments. -- Is the PLIP consistent with the rest of Plone? - For example, if there is control panel configuration, does the new form fit in with the rest of the panels? -- Does everything flow nicely for novice and advanced users? - Is there any workflow that feels odd? -- Are there any new permissions and do they work properly? - Does their role assignment make sense? - - -### Documentation Issues - -- Is the corresponding documentation for the end user, be it developer or Plone user, sufficient? -- Is the change itself properly documented? - -Report bugs or issues on GitHub as you would for any Plone bug. -Reference the PLIP in the bug, assign to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. -This way the implementer can find help if they need it. -Also set a priority for the ticket. -The PLIP will not be merged until all blockers and critical bugs are fixed. - - -### Code Review - - -#### Python - -- Is this code maintainable? -- Is the code properly documented? -- Does the code adhere to PEP8 standards (more or less)? -- Are they importing deprecated modules? - - -#### JavaScript - -- Does the JavaScript meet our set of JavaScript standards? - See our section about [JavaScript](https://5.docs.plone.org/develop/addons/javascript/index.html) and the [JavaScript Style Guide](https://5.docs.plone.org/develop/styleguide/javascript.html). -- Does the JavaScript work in all currently supported browsers? - Is it performant? - -```{todo} -Update links from Plone 5 Documentation to Plone 6 Documentation, when they exist. -See https://github.com/plone/documentation/issues/1330 -``` - -#### ME/TAL - -- Does the PLIP use views appropriately, avoiding too much logic? -- Is there any code in a loop that could potentially be a performance issue? -- Are there any deprecated or old style ME/TAL lines of code, such as using `DateTime`? -- Is the rendered HTML compliant with standards? Are IDs and classes used appropriately? diff --git a/coredev/plips.md b/coredev/plips.md deleted file mode 100644 index 408793d47..000000000 --- a/coredev/plips.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -myst: - html_meta: - "description": "Plone Improvement Proposals (PLIPs)" - "property=og:description": "Plone Improvement Proposals (PLIPs)" - "property=og:title": "Plone Improvement Proposals (PLIPs)" - "keywords": "Plone Improvement Proposal, PLIP)" ---- - -# Plone Improvement Proposals (PLIPs) - -A PLIP is a Plone Improvement Proposal. -It is a change to a Plone package that would affect everyone. -PLIPs go through a different process than bug fixes because of their broad reaching effect. -The Plone Framework Team reviews all PLIPs to be sure that it's in the best interest of the broader community to be implemented and that it is of high quality. - - -## Frequently asked questions about PLIPs - -This section provides detailed answers to common questions about PLIPs. - - -### PLIP or bugfix? - -In general, anything that changes the API of Plone in the backend or the user interface (UI) on the front end should be filed as a PLIP. -When in doubt, submit it as a PLIP. -The Framework Team is eager to reduce its own workload and will reclassify it for you. -If the change you are proposing is not in the scope of a PLIP, a GitHub pull request or issue is the right format. -The key point here is that each change must be documented, allowing it to be tracked and understood. - - -### Who can submit PLIPs? - -Anyone who has signed a Plone Contributor Agreement can work on a PLIP. -Don't let the wording freak you out: signing the agreement is easy and you will get access almost immediately. - -You do not have to be the most amazing coder in the entire world to submit a PLIP. -The Framework Team is happy to help you at any point in the process. - -Submitting a PLIP can be a great learning process. -We encourage people of all backgrounds to submit a PLIP. -When the PLIP is accepted, a Framework Team member will "champion" your PLIP and be dedicated to its completion. - -PLIPs are not just for code monkeys. -If you have ideas on new interactions or UI your ideas are more than welcome. - -We will help you pair up with implementers if needed. - - -### What is a PLIP champion? - -When you submit your PLIP and it is approved, a Framework Team member who is especially excited about seeing the PLIP completed will be assigned to your PLIP as a champion. - -They are there to push you through completion, as well as answer any questions and provide guidance. - -A champion fulfill the following tasks. - -- Answer any questions the PLIP implementor has, technical or otherwise. -- Encourage the PLIP author by constantly giving feedback and encouragement. -- Keep the implementer aware of timelines, and push to get things done on time. -- Assist with finding additional help when needed to complete the implementation in a timely matter. - -Keep in mind that champions are in passive mode by default. -If you need help or guidance, please reach out to them as soon as possible to activate help mode. - - -### Can I get involved in other ways? - -If you want to experience the process and how it works, help us review PLIPs as the implementations finish up. -Ask one of the Framework Team members what PLIPs are available for review, or check the status of PLIPs at the [GitHub issues](https://github.com/plone/Products.CMFPlone/issues) page -for [Products.CMFPlone](https://github.com/Plone/Products.CMFPlone) -for [issues tagged with "03 type: feature (plip)"](https://github.com/plone/Products.CMFPlone/labels/03%20type%3A%20feature%20%28plip%29). - -Make sure to let us know you intend to review the PLIP by communicating that to the [Framework Team](https://community.plone.org/c/development/framework-team). - -Then, follow the instructions for {doc}`reviewing a PLIP `. - -Thank you in advance! - - -### When can I submit a PLIP? - -Today, tomorrow, any time! - -After the PLIP is accepted, the Framework Team will try to judge complexity and time to completion, and assign it to a milestone. - -You can begin work immediately, and we encourage submitting fast and furious. - - -### When is the PLIP due? - -**Summary: As soon as you get it done.** - -Technically, we want to see it completed for the release to which it's assigned. -We know that things get busy, and new problems may make PLIPs more complicated, and we will push it to the next release. - -In general, we don't want to track a PLIP for more than a year. - -If your PLIP is accepted and we haven't seen activity in over a year, we will probably ask you to restart the whole process. - - -### What happens if your PLIP is not accepted? - -If a PLIP isn't accepted in core, it doesn't mean it's a bad idea. -It is often the case that there are competing implementations, and we want to see it vetted as an add-on before "blessing" a preferred implementation. - - -## Process Overview - -1. Submit a PLIP at any time. -2. PLIP is approved for inclusion into core for a given release. -3. Developer implements PLIP (code, tests, documentation). -4. PLIP is submitted for review by developer. -5. Framework Team reviews the PLIP and gives feedback. -6. Developer addresses concerns in feedback and re-submits the PLIP, if necessary. -7. This may go back and forth a few times, until both the Framework Team and developer are happy with the result. -8. PLIP is approved for merge. - In rare circumstances, a PLIP will be rejected. - This is usually the result of the developer not responding to feedback or dropping out of the process. - Hang in there! -9. After all other PLIPs are merged, a release is cut. - Standby for bugs! - - -(how-to-submit-a-plip)= - -## How to submit a PLIP - -Whether you want to update the default theme, or rip out a piece of architecture, everyone should go through the PLIP process. -If you need help at any point in this process, please contact a member of the Framework Team personally or ask for help at the [Framework Team Space](https://community.plone.org/c/development/framework-team). - -A PLIP is a [GitHub issue](https://github.com/plone/Products.CMFPlone/issues/new) on [`Products.CMFPlone`](https://github.com/Plone/Products.CMFPlone) with a special template and a specific tag. - -To get started, open a new issue. -The issue will be prefilled with headings and comments for a bug or a PLIP. -Remove the bug part. -Fill in all applicable fields. -After submitting, select the tag `03 type: feature (plip)` for the issues. - -When writing a PLIP, be as specific and to-the-point as you can. -Remember your audience. -To get support for your proposal, people will have to be able to read it! - -A good PLIP is sufficiently clear for a knowledgeable Plone user to understand the proposed changes, and sufficiently detailed for the release manager and other developers to understand the full impact the proposal would have on the code base. - -You don't have to list every line of code that needs to be changed, but you should also give an indication that you have some idea of how the change can be feasibly implemented. - -After your PLIP is written, solicit feedback on your idea on the [Plone Community Forum](https://community.plone.org/). -In this vetting process, you want to make sure that the change won't adversely affect other people on accident. -Others may be able to point out risks or even offer up better or existing solutions. - -Please note a few things: - -- It is very rare that the "Risks" section will be empty or none. -- If you find this is the case, and your PLIP is anything more than trivial, maybe some more vetting should be done. -- The seconder field is REQUIRED. - -We will send the PLIP back to you if it is not filled in. -Currently, this is just someone else who thinks your PLIP is a good idea, a +1. - -In the near future, we will start asking that the seconder is either a coding partner, or someone who is willing and able to finish the PLIP should something happen to the implementer. - - -### Evaluating PLIPs - -After you submit your PLIP, the Framework Team will meet within a couple weeks, and let you know if the PLIP is accepted. -If the PLIP is not accepted, please don't be sad! - -We encourage most PLIPs to go through the add-on process at first, if at all possible, to make sure the majority of the community uses it. - -All communication with you occurs on the PLIP issue itself. -Please keep your eyes and inbox open for changes. - -These are the criteria by which the framework team will review your work: - -- What is size and status of the work needed to be done? -- Is it already an add-on and well established? -- Is this idea well baked and expressed clearly? -- Does the work proposed belong in Plone now, or in the future? -- Is this PLIP more appropriate as a qualified add-on? -- Is this PLIP too risky? - -See the {doc}`plip-review` page for more information. - - -## Implementing your PLIP - -You can start the development at any time, but if you are going to modify Plone itself, it is a good idea to wait to see if your idea is approved. - - -### General Rules - -- Any new packages must be in a branch in the `plone` namespace in GitHub. - You don't have to develop there, but it must be there when submitted. - We recommend using branches off of the repositories under the Plone GitHub organization, and will detail that below. -- Most importantly, the PLIP reviewers must be able run buildout and everything should "just work"™. -- Any new code must: - - - Be {doc}`properly documented `. - - Have clear code. - - [Follow our style guides](https://5.docs.plone.org/develop/styleguide/index.html). - For convenience and better code quality use Python, JavaScript, and other code linting plugins in your editor. - - [Be tested](https://5.docs.plone.org/develop/testing/index.html). - -```{todo} -Update links from Plone 5 to Plone 6 Documentation, once content is migrated. -See https://github.com/plone/documentation/issues/1330 and other issues. -``` - - -### Creating a new PLIP branch - -Create a buildout configuration file for your PLIP in the `plips` folder. -Give it a descriptive name, starting with the PLIP number, for example, {file}`plip-1234-widget-frobbing.cfg`. - -The PLIP number is your PLIP's issue number. - -This file will define the branches you're working with in your PLIP, along with other buildout configuration. - -It should look something like the following, such as in a file {file}`plips/plip-1234-widget-frobbing.cfg`. - -```ini -[buildout] -extends = plipbase.cfg -auto-checkout += - plone.somepackage - plone.app.someotherpackage - -[sources] -plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-1234-widget-frobbing -plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-1234-widget-frobbing - -[instance] -eggs += - plone.somepackage - plone.app.someotherpackage -zcml += - plone.somepackage - plone.app.someotherpackage -``` - -Use the same naming convention when you branch existing packages. -You should always branch packages when working on PLIPs. - - -### Working on a PLIP - -To work on a PLIP, you bootstrap buildout, and then invoke buildout with your PLIP configuration: - -```shell -virtualenv . -./bin/pip install -r requirements.txt -./bin/buildout -c plips/plip-1234-widget-frobbing.cfg -``` - -If you are using a {file}`local.cfg` to extend your PLIP file with some changes that you do not want to commit accidentally, be aware that you need to override some settings from {file}`plipbase.cfg` to avoid some files being created in the {file}`plips` directory or in the directory above the buildout directory. -This is done as shown below. - -```ini -[buildout] -extends = plips/plip-1234-widget-frobbing.cfg -develop-eggs-directory = ./develop-eggs -bin-directory = ./bin -parts-directory = ./parts -sources-dir = ./src -installed = .installed.cfg - -[instance] -var = ./var -``` - - -### Finishing up - -Before marking your PLIP as ready for review, please add a file to give a set of instructions to the PLIP reviewer. -This file should be called {file}`plip__notes.txt`. -This should include, but is not limited to: - -- URLs pointing to all documentation created and updated -- Any concerns and issues still remaining -- Any weird buildout things - -Once you have finished, update your PLIP issue to indicate that it is ready for review. -The Framework Team will assign 2-3 people to review your PLIP. -They will follow the guidelines listed at {doc}`plip-review`. - -After the PLIP has been accepted by the Framework Team and the release manager, you will be asked to merge your work into the main development line. -Merging the PLIP in is not the hardest part, but you must think about it when you develop. - -You'll have to interact with a large number of people to get it all set up. -The merge may cause problems with other PLIPs coming in. -During the merge phase you must be prepared to help out with all the features and bugs that arise. - -If all went as planned, the next Plone release will carry on with your PLIP in it. -You'll be expected to help out with that feature after it's been released (within reason). diff --git a/coredev/roboto.md b/coredev/roboto.md deleted file mode 100644 index 89d42038f..000000000 --- a/coredev/roboto.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -myst: - html_meta: - "description": "Mr. Roboto" - "property=og:description": "Mr. Roboto" - "property=og:title": "Mr. Roboto" - "keywords": "Mr. Roboto, mr.roboto, Plone" ---- - -# Mr. Roboto - -```{todo} -Add brief description of what is Mr. Roboto and what it does. -``` - -## GitHub push - -When a push happens on GitHub, `mr.roboto` is triggered and it starts to analyze the push. - -- If it's on `buildout-coredev`, it starts the job of the branch that has been pushed. - In this case, we send to `plone-cvs` the commit to keep track of the commits on that list. -- If it's on a package that's on the {file}`sources.cfg` of a `buildout-coredev`, it starts the coredev jobs that are linked to that package and a kgs job with that package. - This kgs job is a snapshot of the last working version of the `buildout.coredev` with the newest version of the package that is involved on the push. - These jobs are really fast, as we only test the package applied to the kgs Plone and Python version `coredev` buildout. -- If it's on a PLIP specification, it runs the job that is configured Through The Web on the `mr.roboto` interface at http://jenkins.plone.org/roboto/plips. - -```{todo} -`http://jenkins.plone.org/roboto/plips` is obsolete, and returns a 404 not found. -``` - - -## Job finishes - -When Jenkins finishes a job, it makes a callback to `mr.roboto`, which in turn does the following: - -- If it comes from a `coredev` job, when all the `coredev` jobs related to that push are finished, it writes a comment on the GitHub commit with all the information. - It does this one time only, with all the information, so no more empty mails from the GitHub notification system. -- If it comes from a kgs job and all the kgs jobs are finished, (that may take max 10 min) and some have failed, we send an email to the testbot mailing list saying that a commit failed on the kgs job. - We also send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. -- If it comes from a kgs job and all the kgs jobs are finished, and all are working, we send an email to [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) with the information to keep track of all the commits. - -For all kgs jobs jenkins sends an email to the author with the results when is finished. - -All the notifications have an URL similar to http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10. - -```{todo} -http://jenkins.plone.org/roboto/get_info?push=9a183de85b3f48abb363fa8286928a10 is obsolete, and returns a 404 not found. -``` - -On this URL, there is the commit hash, who committed it, the diff, the files, and the result for each Jenkins job. - -- [plone-testbot](https://lists.plone.org/mailman/listinfo/plone-testbot) mailing list receives messages only when a test fails on the kgs environment, and may take up to ten minutes from the push. -- [plone-cvs](https://sourceforge.net/projects/plone/lists/plone-cvs) always has the commit, diff, and the information, and it may take ten minutes to get there after the push. -- The author receives the results of tests failing against kgs after ten minutes after the push. - -```{note} -In case of integration errors with other packages that may fail because of the push, kgs will not be aware of that. -It's important that at the end (and after the fifty minutes that takes the `coredev` jobs to complete), that you also check the latest version of `coredev` with your push. -``` diff --git a/coredev/troubleshooting.md b/coredev/troubleshooting.md deleted file mode 100644 index db636fd80..000000000 --- a/coredev/troubleshooting.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -myst: - html_meta: - "description": "Troubleshooting development issues in Plone" - "property=og:description": "Troubleshooting development issues in Plone" - "property=og:title": "Troubleshooting development issues in Plone" - "keywords": "Troubleshooting, development issues, Plone" ---- - -# Troubleshooting - -This chapter describes how to troubleshoot development issues in Plone. - - -## Buildout issues - -Buildout can be frustrating for those unfamiliar with parsing through autistic robot language. -These errors are almost always a quick fix, and a little bit of understanding goes a long way. - - -### Errors running `bootstrap.py` - -You may not even get to running buildout, and then you will already have an error. -Let's take this one for example: - -```console - File "/usr/local/lib/python2.6/site-packages/distribute-0.6.13-py2.6.egg/pkg_resources.py", line 556, in resolve - raise VersionConflict(dist,req) # XXX put more info here - pkg_resources.VersionConflict: (zc.buildout 1.5.1 (/usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg), Requirement.parse('zc.buildout==1.5.2')) -``` - -Buildout has simply noticed that the version of buildout required by the file `bootstrap.py` you are trying to run does not match the version of buildout in your Python library. -In the error above, your system has buildout 1.5.1 installed and the `bootstrap.py` file wants to run with 1.5.2. - -To fix, you have a couple options. -First, you can force buildout to run with the version you already have installed by invoking the version tag. -This tells your Plone `bootstrap.py` file to play nicely with the version that you already have installed. -In the case of the error pasted above, that would be: - -```shell -python bootstrap.py --version=1.5.1 -``` - -I personally know that versions 1.4.4, 1.5.1, and 1.5.2 all work this way. - -The other option is to delete your current egg and force the upgrade. -In the case of the error above, delete the egg the system currently has, for example: - -```shell -rm -rf /usr/local/lib/python2.6/site-packages/zc.buildout-1.5.1-py2.6.egg -``` - -When you rerun bootstrap, it will look for the buildout of the egg, note that there isn't one, and then go fetch a new egg in the version that it wants for you. - -Do one of those and re-run bootstrap. - -One other thing of note is that running bootstrap effectively ties that Python executable and all of its libraries to your buildout. -If you have several Python installs, and want to switch which Python is tied to your buildout, simply rerun `bootstrap.py` with the new Python (and then rerun buildout). -You may get the same error above again, but now that you know how to fix it, you can spend that time drinking beer instead of smashing your keyboard. - -Hooray! - - -### When `mr.developer` is unhappy - -`mr.developer` is never unhappy, except when it is. -Although this technically isn't a buildout issue, it happens when running buildout, so I'm putting it under buildout issues. - -When working with the dev instance, especially with all the moving back and forth between GitHub and Subversion, you may have an old copy of a `src` package. -The error looks like: - -```console -mr.developer: Can't update package 'Products.CMFPlone' because its URL doesn't match. -``` - -As long as you don't have any pending commits, you just need to remove the package from {file}`src/` and it will recheck it out for you when it updates. - -You can also get such fun errors as: - -```console -Link to http://sphinx.pocoo.org/ ***BLOCKED*** by --allow-hosts -``` - -These are OK to ignore if and only if the lines following it say: - -```console -Getting distribution for 'Sphinx==1.0.7'. -Got Sphinx 1.0.7. -``` - -If buildout ends with warning you that some packages could not be downloaded, then chances are that package wasn't downloaded. -This is bad and could cause all sorts of whack out errors when you start or try to run things because it never actually downloaded the package. - -There are two ways to get this error to go away. - -The first is to delete all instances of host filtering. -Go through all the files and delete any lines which say `allow-hosts =` and `allow-hosts +=`. -In theory, by restricting which hosts you download from, buildout will go faster. -The point is that they are safely deletable. - -The second option is to allow the host that it is pointing to by adding something like this to your `.cfg`: - -```cfg -allow-hosts += sphinx.pocoo.org -``` - -Again, this is only necessary if the package wasn't found in the end. - - -### `mr.developer` path errors - -```console -ERROR: You are not in a path which has mr.developer installed (:file:`.mr.developer.cfg` not found). -``` - -When running any {command}`./bin/develop` command. - -To fix, do: - -```shell -ln -s plips/.mr.developer.cfg -``` - - -## Other random issues - -```{TODO} -These need to be revalidated -``` - - -### Dirty packages - -```console -ERROR: Can't update package 'Some package', because it's dirty. -``` - - -#### Fix - -`mr.developer` is complaining because a file has been changed or added, but not committed. - -Use `bin/develop update --force`. -Adding `*.pyc *~.nib *.egg-info .installed.cfg *.pt.py *.cpt.py *.zpt.py *.html.py *.egg` to your subversion configuration's `global-ignores` has been suggested as a more permanent solution. - - -### No module named zope 2 - -```console -ImportError: No module named Zope2" when building using a PLIP cfg file. -``` - -Appears to not actually be the case. -Delete {file}`mkzopeinstance.py` from {file}`bin/`, and rerun buildout to correct this if you're finding it irksome. - - -### Can't open file '/Startup/run.py' - -Two possible fixes. - -If you use Python 2.4 by mistake, use 2.6 instead. - -Or you may need to make sure you run `bin/buildout …` after `bin/develop …`. -Try removing {file}`parts/*`, {file}`bin/*`, {file}`.installed.cfg`, then re-bootstrap and re-run buildout, develop, buildout. - - -### Missing PIL - -{file}`pil.cfg` is included within this buildout to aid in PIL installation. -Run {command}`bin/buildout -c pil.cfg` to install. -This method does not work on Windows. -We're unable to run it by default. - - -### Modified egg issues - -{command}`bin/develop status` is showing that the `Products.CMFActionIcons` egg has been modified, but I haven't touched it. -And this is preventing `bin/develop up` from updating all the eggs. - -#### Fix - -Edit {file}`~/.subversion/config` and add `eggtest\*.egg` to the list of `global-ignores`. diff --git a/docs/conf.py b/docs/conf.py index 00877dcf4..13a8ca8af 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,7 @@ "sphinx.ext.viewcode", # plone.api "sphinx.ext.autosummary", # plone.api "sphinx.ext.graphviz", + "sphinxcontrib.mermaid", "notfound.extension", ] @@ -99,6 +100,8 @@ r"https://stackoverflow.com", # volto and documentation # TODO retest with latest Sphinx. r"https://web.archive.org/", # volto r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube + r"https://www.upc.edu/en", # TODO remove after their certificate is fixed + r"http://z3c.pt", # fluke where Sphinx interprets this as a URL ] linkcheck_anchors = True linkcheck_timeout = 5 @@ -122,6 +125,7 @@ "**/CONTRIBUTORS.rst", "**/LICENSE.rst", "**/README.rst", + "contributing/core/continuous-integration.md", "plone.restapi/.*", "plone.restapi/bin", "plone.restapi/docs/source/glossary.md", # There can be only one Glossary. @@ -179,6 +183,8 @@ "fawrench": '', } +mermaid_version = "10.9.1" + # -- Intersphinx configuration ---------------------------------- # This extension can generate automatic links to the documentation of objects @@ -197,6 +203,7 @@ # the entire Plone Documentation is built. intersphinx_mapping = { "plone": ("https://6.docs.plone.org/", None), # for imported packages + "plone5": ("https://5.docs.plone.org/", None), "python": ("https://docs.python.org/3/", None), "training": ("https://training.plone.org/", None), "training-2022": ("https://2022.training.plone.org/", None), @@ -329,6 +336,7 @@ "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github", } + # An extension that allows replacements for code blocks that # are not supported in `rst_epilog` or other substitutions. # https://stackoverflow.com/a/56328457/2214933 diff --git a/docs/contributing/core/continuous-integration.md b/docs/contributing/core/continuous-integration.md new file mode 100644 index 000000000..9cf3e6fda --- /dev/null +++ b/docs/contributing/core/continuous-integration.md @@ -0,0 +1,111 @@ +--- +myst: + html_meta: + "description": "Essential continuous integration practices" + "property=og:description": "Essential continuous integration practices" + "property=og:title": "Essential continuous integration practices" + "keywords": "Plone, continuous integration, best practices" +--- + +# Essential continuous integration practices + +The {term}`CI` system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code. + +Build breakages are a normal and expected part of the development process. +The aim is to find errors and remove them as quickly as possible, without expecting perfection and zero errors. +However, 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 +- 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. +Other developers may have checked in changes since your last synchronization. +These may interact with your work. + +Therefore it's essential that you merge changes from the main branch into your feature branch, then run the tests again, before you push your changes to GitHub. + +A common source of errors on check-in is to forget to add some files to the repository. +Use {command}`git status` to check and correct for this. +Also double-check to not check in files that should not be part of a package, such as editor configuration files and git submodules. + + +## 3) Wait for commit tests to pass before moving on + +Always monitor the build's progress, and fix the problem right away if it fails. +If you introduced a regression, you have a far better chance of fixing the build sooner than later. +Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for you. + + +## 4) Never go home on a broken build + +Take into account the first rule of CI ("Don't check in on a broken build"). +Breaking the build essentially stops all other developers from working on it. +Therefore going home on a broken build—or even on a build that has not finished yet—is _not_ acceptable. +It will prevent all other developers from working, or they will need to fix the errors that you introduced. + + +## 5) Always be prepared to revert to the previous revision + +For other developers to work on the build, you should always be prepared to revert to the previous passing revision. + + +## 6) Time-box fixing before reverting + +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 quickly as possible. +While this impulse is understandable, it is _not acceptable_. + +The tests were passing for a while and then start to fail. +This means that you either caused a regression, made assumptions that are no longer valid, or the application has changed the functionality being tested for a valid reason. + +You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists). + + +## 8) Take responsibility for all breakages that result from your changes + +If you commit a change and all the tests you wrote pass, but others break, the build is still broken. +This also applies to tests that fail in `buildout.coredev` and don't belong directly to the package you worked on. +This means that you have introduced a regression bug into the application. + +It is _your responsibility_ to fix all tests that do not pass because of your changes. + +There are some tests in Plone that fail randomly, and the community is always working on fixing those. +If you think you hit such a test, try to fix it or re-run the Jenkins job to see if it passes again. + +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/coredev/documentation.md b/docs/contributing/core/documentation.md similarity index 52% rename from coredev/documentation.md rename to docs/contributing/core/documentation.md index a09ec6bf8..ff06f57cf 100644 --- a/coredev/documentation.md +++ b/docs/contributing/core/documentation.md @@ -1,27 +1,26 @@ --- myst: html_meta: - "description": "Writing documentation of Plone" - "property=og:description": "Writing documentation of Plone" - "property=og:title": "Writing documentation of Plone" + "description": "Write documentation of Plone" + "property=og:description": "Write documentation of Plone" + "property=og:title": "Write documentation of Plone" "keywords": "documentation, Plone" --- -# Writing documentation +# Write documentation -For general guidance for contributing documentation, see {doc}`contributing/index`. - -For documentation authors, see {doc}`contributing/authors`. +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 https://6.docs.plone.org/. The documentation repository is on [GitHub](https://github.com/plone/documentation). -Information for how to contribute to documentation can be found at {doc}`contributing/index`. +Information for how to contribute to documentation can be found at {doc}`/contributing/documentation/index`. -## Documenting a package +## Document a package At the very least, your package should include the following forms of documentation. @@ -33,25 +32,29 @@ It should be formatted using [GitHub flavored Markdown](https://github.github.co `README.md` should include: -- A brief description of the package's purpose. -- Installation information (How do I get it working?) -- Compatibility information (what versions of Plone does it work with?) -- Links to other sources of documentation. -- Links to issue trackers, mailing lists, and other ways to get help. +- A brief description of the package's purpose +- Installation information +- Version compatibility information +- Links to other sources of documentation +- Links to issue trackers, mailing lists, and other ways to get help + +```{seealso} +{ref}`github-community-health-files-label` +``` ### The manual (narrative documentation) -The manual goes into further depth for people who want to know all about how to use the package. +The manual should go into further depth for people who want to know all about how to use the package. -It includes topics like: +It should include topics like: - What are its features - How to use them (in English—not doctests!) - Information about architecture - Common gotchas -The manual should consider various audiences who may need different types of information: +The manual should address various audiences who may need different types of information: - End users who use Plone for content editing, but don't manage the site. - Site administrators who install and configure the package. @@ -63,7 +66,7 @@ In this case, it's simplest to include it in an extended `README.md`. Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching. If your project is moderately complex, you may want to set up your documentation with multiple pages. -The preferred way to do this is to add Sphinx to your project, and host your docs on readthedocs.org, so that it rebuilds the documentation whenever you push to GitHub. +The preferred way to do this is to add Sphinx to your project, and host your docs on [readthedocs.org](https://about.readthedocs.com/), so that it rebuilds the documentation whenever you push to GitHub. If you do this, your `README.md` must link off site to the documentation. @@ -72,39 +75,28 @@ If you do this, your `README.md` must link off site to the documentation. An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code). It is meant for random access to remind the reader of how a particular class or method works, rather than for reading in its entirety. -If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx. +If the code base is written with docstrings, API documentation can be automatically generated using Sphinx. ### Changes or history -```{todo} -Update for towncrier. -Probably purge all this content. +```{seealso} +- {ref}`contributing-change-log-label` +- Volto's [`towncrier.toml`](https://github.com/plone/volto/blob/main/packages/volto/towncrier.toml) as an example towncrier configuration file. ``` -The changelog is a record of all the changes made to the package and who made them, with the most recent changes at the top. -This is maintained separately from the git commit history to give a chance for more user-friendly messages and to and record when releases were made. - -A changelog looks something like: - -```text -Changelog -========= - -1.0 (2012-03-25) ----------------- -* Documented changelogs. - [davisagli] -``` +### Licenses -See for a full example. +Information about the open source license used for the package should be placed where GitHub can pick it up and display it as one of its [community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). +The preferred location is at the root of the repository. -If a change was related to a bug in the issue tracker, the changelog entry should include a link to that issue. +For Plone core packages, this includes `LICENSE.md` and {file}`LICENSE.GPL`. -### Licenses +(github-community-health-files-label)= -Information about the open source license used for the package should be placed within the `docs` directory. +### GitHub community health files -For Plone core packages, this includes `LICENSE.md` and {file}`LICENSE.GPL`. +If your Plone core package lacks a specific community health file, then GitHub will pick up the one configured in the Plone GitHub organization repository [`.github`](https://github.com/plone/.github). +You can override the default files by placing your health file as described in the documentation of [GitHub community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md new file mode 100644 index 000000000..0a02f6691 --- /dev/null +++ b/docs/contributing/core/index.md @@ -0,0 +1,313 @@ +--- +myst: + html_meta: + "description": "Contribute to Plone 6 Core" + "property=og:description": "Contribute to Plone 6 Core" + "property=og:title": "Contribute to Plone 6 Core" + "keywords": "Plone, Plone Contributor Agreement, License" +--- + +# Contribute to Plone 6 core + +This guide describes the process of how to contribute to, and develop in, Plone core. +It expands upon {doc}`/contributing/index`. + +```{important} +Although Plone core includes Volto—the React based, default frontend for Plone 6—this guide does not apply to Volto and its packages. +To contribute to Volto, see {doc}`../volto`. +``` + +This guide assumes that you have basic knowledge of how to use git and GitHub. +If you have never contributed to Plone, or you lack basic knowledge of how to use git and GitHub, you should first read {doc}`/contributing/first-time` for more information. + +```{important} +You must {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before your contribution can be accepted. +``` + + +## Version support policy + +Before you contribute to Plone core, check the [version support policy](https://plone.org/download/release-schedule) to see which versions of Plone are currently supported. + + +## Pre-requisites + +It is beyond the scope of this documentation to provide installation instructions for all pre-requisites for your operating system. +However, the following links and sections below may be helpful. + +```{include} ../../volto/contributing/install-operating-system.md +``` + +- Python {SUPPORTED_PYTHON_VERSIONS} +- {term}`GNU make` +- {term}`Git` +- A C compiler + + +### Python + +Installing Python is beyond the scope of this documentation. +However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. +Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. + + +### Make + +```{include} ../../volto/contributing/install-make.md +``` + + +### Git + +```{include} ../../volto/contributing/install-git.md +``` + +### C compiler + +You need a C compiler on your system to compile some of the Python libraries that Plone uses. + +On macOS, Developer Tools provides Clang for a C compiler. + +On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common option. + + + +## Install Plone core for development + +The tool that installs Plone core is `buildout.coredev`. + +The current default and development branch of `buildout.coredev` is `6.1` +Older versions are named according to their `major.minor` version. +Its versions align with Plone's `major.minor` versions. + +Use a separate directory for each version of Plone to which you want to contribute. +This will avoid switching between git branches, then re-running buildout, which can cause dependency conflicts between versions of Plone. + +To set up a Plone 6 development environment, change your working directory to wherever you place your projects, and clone https://github.com/plone/buildout.coredev. +You can specify the branch that you want to check out with the `-b` option. + +```shell +cd [MY_PROJECTS] +# clone a specific major.minor version branch +git clone -b 6.1 https://github.com/plone/buildout.coredev +cd buildout.coredev +``` + +````{important} +If you want to use a Python version that is not 3.11, follow these instructions. + +Open the file {file}`bootstrap.sh` at the root of the repository. +Notice that the script expects Python 3.11 to be installed on your system and in your user's `PATH`. + +```shell +#/bin/sh +`which python3.11` -m venv . +``` + +Edit it according to the Python version you want to use, then save and close the file. +After you have run the script, you should undo the change, otherwise you have a local change in git that you might accidentally commit. +```` + +Now run the script to install Plone 6. + +```shell +./bootstrap.sh +``` + +This will run for a long time if it's your first pull (approximately 10-20 minutes, depending on network speed and your hardware). + +Once that's done, you can start an instance of Plone with the following command. + +```shell +./bin/instance fg +``` + +To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser. + +You will be presented with several options. +Click the button {guilabel}`Create Classic UI Plone site`. + +Enter values in the form, and click the button {guilabel}`Create Plone Site`. + +You will be redirected to your new Classic UI Plone site. + +```{warning} +Ignore the warning about accessing the Plone backend through its Classic UI frontend. + +Do not follow the instructions to install Volto. +They will not work with buildout. +To contribute to Volto, you will need to start over, and follow {doc}`../volto`. +``` + +To login, the default credentials are the following. + +- username: `admin` +- password: `admin` + + +## Work with git + +```{important} +This section applies to members of the GitHub `plone/developers` team, who have write access to repositories under the Plone GitHub organization. + +Members of the `plone/contributors` team do not have write access, and instead must follow the process to set up their remote upstream and origin branches as described in {ref}`set-up-your-environment-label`. +``` + +Always begin by checking out the git branch on which you want to work. +This is the base branch to which you will create a pull request. + +If you just cloned `https://github.com/plone/buildout.coredev`, then the `6.1` branch is checked out and current, and you can skip the rest of this section and continue on the next, {ref}`contributing-core-edit-packages-label`. + +```shell +git checkout 6.1 +``` + +Next pull down and merge any recent changes from the remote tracked repository with a single command. + +```shell +git pull +``` + + +(contributing-core-edit-packages-label)= + +## Edit packages + +First identify the names of the Plone packages you want to work on. +If you do not know, you can ask in the [Plone Community Forum](https://community.plone.org/). +Only a few packages are in {file}`src/` by default. + +Next create a new file {file}`buildout.local.cfg`, and add the names of packages that you want to develop under the `auto-checkout` list. + +```ini +[buildout] +extends = + buildout.cfg + +auto-checkout = + # Add packages that you want to develop + plone.app.event + icalendar + # others + ... +``` + +When you make changes in your package, then rerun buildout with the following command, specifying your new buildout configuration file with the `-c` option. +You can add the `-N` flag to save time by not checking PyPI to see if there are updates to packages that were already installed. + +```shell +./bin/buildout -c buildout.local.cfg -N +``` + +```{seealso} +`mr.developer` checks out additional repositories using the `auto-checkout` option. +For more information, see {doc}`mrdeveloper`. +``` + +````{tip} +To avoid conflicts with `buildout.coredev` files, you can configure git for your user. +Either create or edit a file at {file}`~/.gitconfig`. +Then add the following stanza to it. + +```cfg +[core] + excludesfile = ~/.gitignore_global +``` + +Then add any standard `.gitignore` syntax to exclude files from getting committed and pushed to a remote repository. +```` + +Next create a new development branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. +It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves. + +```shell +git switch -c 123-thing-i-fixed +``` + +Now you can edit your code without affecting the original branch. + + +(contributing-core-test-locally-label)= + +## Test locally + +If you change the expected behavior of a feature in a package, you should write a test to cover the change. + +To run a test for the specific package that you modified, use the `-s` option followed by the package name, as shown in the following example. + +```shell +./bin/test -s plone.app.event +``` + +If any test fails, do not commit and push the changes. +Instead write a test that passes. + +After the package level tests pass with your change, you can {ref}`contributing-core-create-a-pull-request-label` and let CI run and ask Jenkins to run the full test suite. + +However, if CI or Jenkins report a test failure that you want to troubleshoot locally, you can run the full unit test suite to ensure other packages aren't affected by the change. +It takes 5-10 minutes to run the full unit test suite. + +```shell +# Run unit tests +./bin/test +``` + +If you run acceptance tests with the `--all` option, it will run tests in a real browser. +This takes 30-40 minutes to run. +This may repeatedly launch and close browser windows that gain focus, disrupting you from doing any other work. +If this happens, you can install the `chromedriver` OS package. +See https://developer.chrome.com/docs/chromedriver. +Then run `export ROBOT_BROWSER="headlesschrome"` and again run `bin/test --all`. + +```shell +# Run acceptance tests +./bin/test --all +``` + + +(contributing-core-change-log-label)= + +## Change log + +All changes require a change log entry. + +For packages that use [towncrier](https://pypi.org/project/towncrier/) to produce change logs, see {ref}`contributing-change-log-label`. +A package that uses towncrier has a `news` directory at its repository or package root. + +For packages that don't use towncrier, edit either {file}`CHANGES.rst`, {file}`CHANGES.txt`, or {file}`HISTORY.txt` in each package you have modified, adding a summary of the change. +New change log entries should be added at the top of {file}`CHANGES.rst`. + + +(contributing-core-create-a-pull-request-label)= + +## Create a pull request + +After you have completed all the foregoing steps, push your changes to a remote branch and create a pull request in GitHub. +If you are working from an issue, include "Fixes #ISSUE-NUMBER" in the description. +This enables automatic closing of the related issue when the pull request is merged. +This also creates a hyperlink to the original issue for easy reference. + + +## Jenkins and mr.roboto + +Plone has a continuous integration ({term}`CI`) setup and follows CI rules. + +When you push a change to a Plone package, there may be GitHub workflows that run automatically. +The CI package [mr.roboto](https://github.com/plone/mr.roboto) will perform some checks and suggest that you run Jenkins after all other CI runs. + +%% See {doc}`continuous-integration` for more information. + + +## Additional material + +```{toctree} +:maxdepth: 1 + +documentation +%% continuous-integration +mrdeveloper +plips +plip-review +package-dependencies +release +``` diff --git a/docs/contributing/core/mrdeveloper.md b/docs/contributing/core/mrdeveloper.md new file mode 100644 index 000000000..114bf9379 --- /dev/null +++ b/docs/contributing/core/mrdeveloper.md @@ -0,0 +1,36 @@ +--- +myst: + html_meta: + "description": "mr.developer" + "property=og:description": "mr.developer" + "property=og:title": "mr.developer" + "keywords": "Plone, buildout, mr.developer" +--- + +# `mr.developer` + +Plone core uses `mr.developer` to manage package development. +See [`mr.developer` on PyPI](https://pypi.org/project/mr.developer/) for more information, or run `bin/develop help` for a list of available commands. + +To get all the latest updates, use the following commands. + +```shell +git pull +bin/develop rebuild +``` + +This will get you the latest `coredev` configuration, check out and update all packages via git in {file}`src`, and run buildout to configure the whole thing. + +From time to time you can check if some old cruft has accumulated. + +```shell +bin/develop status +``` + +If this prints any lines with a question mark (`?`) in front, you can clean the cruft with the following command. + +```shell +bin/develop purge +``` + +This will remove packages from {file}`src/` which are no longer needed, as they have been replaced by proper egg releases of these packages. diff --git a/coredev/packages-dependencies.md b/docs/contributing/core/package-dependencies.md similarity index 65% rename from coredev/packages-dependencies.md rename to docs/contributing/core/package-dependencies.md index 5f673b7ce..de5c10c23 100644 --- a/coredev/packages-dependencies.md +++ b/docs/contributing/core/package-dependencies.md @@ -14,9 +14,9 @@ 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. +Over the years, Plone has developed many indirections in its packages and dependencies. +The goal in the long run is to untangle them and get a simple dependency graph. +This document shows the current state, as an orientation to its architecture. ## Overview @@ -28,73 +28,67 @@ There are multiple level of dependencies: - 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. +Circular dependencies at the package level have now been resolved. -Nevertheless we have indirection on all other levels. +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 since alpha 4 is shown in the following diagram: +A base mental model for how Plone is organized in Plone 6, and is shown in the following diagram: + +```{mermaid} +block-beta + columns 1 + + Plone["Plone
the integraton of both distributions in one release"] + space + Distributions + block:dist + plone.volto + plone.classicui + end + space + block:core + coreaddons["Core add-ons"] + coreapi["Core APIs"] + end + space + cmfplone["Products.CMFPlone"] + + space:2 + + block:layer + ploneapp["Most of plone.app.* namespace"] + otherlay["Various other packages"] + end + +space + + plonebase["plone.base"] + space + foundations["The Foundations"] + space:3 + block:foundationcomponents + ploneworld["Plone world"] + zopeeco["Zope ecosystem"] + zopecore["Zope core"] + libraries["Libraries"] + end + Plone --> Distributions + dist --> core + cmfplone --> layer + core --> cmfplone + layer --> plonebase + plonebase --> foundations + + style cmfplone fill:#ff0 + style plonebase fill:#ff0 -``` -┌────────────────────────────┐ -│ "Plone" | -| The Integration of both | -| distributions in one | -| Release | -├────────────────────────────┤ -| Distributions: | -| - plone.volto | -| - plone.classicui | -├────────────────────────────┤ -│ Core-Addons │ -│ - plone.distribution │ -│ - plone.app.exportimport │ -│ - plone.app.discussion │ -│ - plone.app.multilingual │ -│ - plone.app.caching │ -│ - plone.app.iterate │ -│ - plone.app.update │ -│ │ -├────────────────────────────┤ -│ Core-APIs │ -│ - plone.restapi │ -│ - plone.api │ -├────────────────────────────┤ -│ │ -│ Products.CMFPlone │ -│ │ -├────────────────────────────┤ -│ │ -│ The space between (core ) │ -│ │ -│ - most of plone.app.* │ -│ - but also some other │ -│ │ -├────────────────────────────┤ -│ │ -│ plone.base │ -│ │ -├────────────────────────────┤ -│ │ -│ The Foundations │ -│ │ -│ - Zope │ -│ - CMFCore │ -│ - PAS/PlonePAS │ -│ - plone.registry │ -│ - plone.dexterity │ -│ - plone.behavior │ -│ - plone.rest │ -│ - .... │ -│ │ -└────────────────────────────┘ ``` -As a rough model we have two packages as dividing lines: +As a rough model, there are two packages as dividing lines: 1. `Products.CMFPlone` 2. `plone.base` @@ -102,9 +96,7 @@ As a rough model we have two packages as dividing lines: ## Packages in detail -If we look deeper into those, we have more sub-dividers, but first group all into the three groups: - -Then, based on the 6.0.0.a4 release, these are the packages: +Looking deeper into those packages, there are more sub-divisions, but first we place them into three groups: ### Above `Products.CMFPlone` diff --git a/docs/contributing/core/plip-review.md b/docs/contributing/core/plip-review.md new file mode 100644 index 000000000..13d06d1ee --- /dev/null +++ b/docs/contributing/core/plip-review.md @@ -0,0 +1,110 @@ +--- +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. +A review of a PLIP ensures that proposed behavior has been implemented as expected. + +Post your PLIP review as a comment in the PLIP pull request. + + +## Set up the environment + +Follow the instructions in {doc}`index`. +You will need to checkout the branch to which the PLIP is assigned. +Instead of running the buildout with the default buildout file, you will run the configuration specific to that PLIP: + +```shell +./bin/buildout -c plips/plip---.cfg +``` + + +## Functionality review + +This section describes the topics that may be addressed in a PLIP review, depending on the nature of the PLIP itself. + +Report bugs or issues you find during the review on GitHub as you would for any Plone bug. +Reference the PLIP in the bug, assign it to its implementer, and add a tag for the PLIP in the form of `plip-xxx`. +This way the implementer can find help if they need it. +Also set a priority for the ticket. +The PLIP will not be merged until all blockers and critical bugs are fixed. + + +### General + +- Take screenshots or videos as necessary, and post them to the pull request with your comments. +- Does the PLIP actually do what the implementers proposed? +- Are there incomplete variations? +- Were there any errors running buildout? +- If there were migrations, did they work? +- Do error and status messages make sense? +- Are messages properly internationalized? +- Are there any performance considerations? + + +### Bugs + +- Are there any bugs? +- Do fields handle unexpected data? +- Is validation function correctly and make sense? +- Is validation too restrictive or not restrictive enough? + + +### Usability issues + +- Is the implementation usable? +- How will end users respond to the change? +- Does this PLIP need a usability review? + If you think this PLIP needs a usability review, add GitHub issue labels {guilabel}`99 tag: UX`, or similar, and {guilabel}`32 needs: review`, and add a note in the comments. +- Is the PLIP consistent with the rest of Plone? + For example, if there is control panel configuration, does the new form fit in with the rest of the panels? +- Does everything flow nicely for all users? +- Are there any new permissions and do they work properly? +- Does permission assignment to roles 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? + + +## Code review + +This section describes considerations of code quality. + + +### Python + +- Is this code maintainable? +- Is the code properly documented? +- Does the code adhere to formatting and style standards? +- Are there any imported deprecated modules? + + +### JavaScript + +- Does the JavaScript satisfy the package's JavaScript standards, or if the package has no standard, then Plone's? + See Plone's section about {doc}`plone5:develop/addons/javascript/index` and the {doc}`plone5:develop/styleguide/javascript`. +- Does the JavaScript work in all currently supported browsers? +- Is the JavaScript performant? + +```{todo} +Update links from Plone 5 Documentation to Plone 6 Documentation, when they exist. +See https://github.com/plone/documentation/issues/1330 +``` + +### ME/TAL + +- 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 `id`s and classes used appropriately? diff --git a/docs/contributing/core/plips.md b/docs/contributing/core/plips.md new file mode 100644 index 000000000..c7b8b17eb --- /dev/null +++ b/docs/contributing/core/plips.md @@ -0,0 +1,193 @@ +--- +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 Plone Improvement Proposal, or {term}`PLIP`, is a change to a Plone package that would affect everyone who uses that package. +PLIPs go through a formal process compared to bug fixes because of their broad reach. +A designated team reviews all PLIPs to make sure that it's in the best interest of the broader community, and that it's of high quality. + +A project board of active PLIPs is located at https://github.com/orgs/plone/projects/47. + + +## Process overview + +1. Developer submits a PLIP and solicits feedback. +2. Developer addresses concerns from the feedback, and resubmits the PLIP, if necessary. +3. The designated team approves the PLIP for inclusion into Plone core for a given release. +4. Developer implements the PLIP, including code, tests, and documentation. +5. Developer creates a pull request of the PLIP for review by the designated team. +6. The designated team reviews the pull request of the PLIP and gives feedback. +7. Repeat the two previous steps, until both the designated team and developer are happy with the result. +8. A designated team member approves the PLIP for merge. +9. A designated team member merges the PLIP. + +In rare circumstances, a PLIP may be rejected. +This is usually the result of the developer not responding to feedback or dropping out of the process. + + +(designated-teams-label)= + +## Designated teams + +The following packages and repositories have designated teams that you can contact by `@`-ing them in its GitHub issue tracker. +If the repository is not listed, use the default repository for `Products.CMFPlone`. + +| Package | Repository | Team | +|---|---|---| +| `Products.CMFPlone` | https://github.com/plone/Products.CMFPlone | `@plone/framework-team` | +| Classic UI | https://github.com/plone/plone.classicui | `@plone/ClassicUI-Team` | +| Volto | https://github.com/plone/volto | `@plone/volto-team` | + + +(submit-a-plip-label)= + +## Submit a PLIP + +Prepare the following information for your PLIP. + +- Title +- Proposer (you) +- Seconder (another person supporting your PLIP) +- Abstract (a comprehensive overview of the subject) +- Motivation (reason or motivation for creating this proposal) +- Assumptions (preconditions) +- Proposal & Implementation (detailed proposal with implementation details and–if needed—possible variants to be discussed) +- Deliverables (packages and documentation chapters involved, including any third party packages) +- Risks (what will break or affect existing installations of Plone after an upgrade, including the end user point of view, training efforts, and other audiences) +- Participants (list of persons and roles known) + +Now that you are prepared, submit your PLIP. + +1. Visit the package's GitHub issue tracker, and Click {guilabel}`New issue`. + + If you do not see the option to create a PLIP, then the repository has not been configured with the PLIP GitHub issue template, and you should instead visit the default Plone issue tracker for PLIPs, [`Products.CMFPlone`](https://github.com/plone/Products.CMFPlone/issues). + +2. For the PLIP option, click {guilabel}`Get started`. + +3. Fill in the title and description. + Preserve the headings and comments. + The comments provide guidance for you to follow while composing your PLIP. + +4. When done, click {guilabel}`Submit new issue` to submit your PLIP. + +5. If GitHub does not automatically assign the label {guilabel}`03 type: feature (plip)`, then assign that label to the issue to make it easier to find. + +6. If GitHub does not automatically add the PLIP to the [PLIP project board](https://github.com/orgs/plone/projects/47), then add it so it can be tracked. + + +## Get feedback + +After you submit your PLIP, solicit feedback for your idea on the [Plone Community Forum](https://community.plone.org/) and through the repository's issue tracker. + +You may revise your PLIP based on feedback. + +If you need help at any point in this process, you can either `@` the team or personally contact a member of the designated team. + + +## Team approves proposal + +After incorporating feedback to your proposal, you can request a final review and approval for inclusion in Plone. +Every PLIP must be approved by the designated team. + + +## Implement your PLIP + +(plip-setup-instructions-label)= + +```{important} +This section does not apply to Volto. +Instead see {doc}`../../volto/contributing/index`. +``` + +```{note} +This section assumes you have read and followed the instructions in {doc}`index` to set up your development environment, up until {ref}`contributing-core-edit-packages-label`. +``` + +You can start the development at any time, but if you intend to modify Plone core, it is a good idea to wait to see if your idea is approved. + + +### General rules + +- Any new packages must be in a branch in the `plone` namespace in GitHub. +- The PLIP reviewers must be able run buildout, and everything should "just work"™. +- New code must: + - Be {doc}`properly documented `. If it ain't documented, it's broken. + - Have clear code. + - Follow current best practices in coding style. + The [Plone Meta](https://github.com/plone/meta) project can help you set up your environment. + - Be tested according to Plone core's {doc}`plone5:develop/testing/index`. + + +### Create a new PLIP branch + +Create a buildout configuration file for your PLIP in the `plips` folder of `buildout.coredev`. +Its name should follow the pattern `plip-repository-issue_number-description.cfg`. +For example, {file}`plip-volto-1234-widget-frobbing.cfg`. + +This file will define the branches for your PLIP, along with other buildout configuration. +The following is example content for the file {file}`plips/plip-volto-1234-widget-frobbing.cfg`. + +```ini +[buildout] +extends = plipbase.cfg +auto-checkout += + plone.somepackage + plone.app.someotherpackage + +[sources] +plone.somepackage = git https://github.com/plone/plone.somepackage.git branch=plip-volto-1234-widget-frobbing +plone.app.someotherpackage = git https://github.com/plone/plone.app.somepackage.git branch=plip-volto-1234-widget-frobbing + +[instance] +eggs += + plone.somepackage + plone.app.someotherpackage +zcml += + plone.somepackage + plone.app.someotherpackage +``` + +Use the same naming convention when you branch existing packages. + + +### Work on a PLIP + +To work on a PLIP, assuming you have followed the {ref}`PLIP set up instructions `, you can invoke buildout with your PLIP configuration as follows. + +```shell +./bin/buildout -c plips/plip-volto-1234-widget-frobbing.cfg +``` + +```{seealso} +See {ref}`contributing-core-test-locally-label`, {ref}`contributing-core-change-log-label`, and {ref}`contributing-core-create-a-pull-request-label`. +``` + + +### Finish up + +Before marking your PLIP as ready for review as a pull request, add a file to give a set of instructions to the PLIP reviewer. +This file should be called {file}`plip___notes.txt`. +This should include, but is not limited to: + +- URLs pointing to all documentation created and updated +- Any concerns and issues still remaining +- Any weird buildout things + +Once you have finished, update your PLIP issue and pull request to indicate that it is ready for review. +The designated team will review your PLIP. +They will follow the guidelines listed at {doc}`plip-review`. + +After the PLIP has been accepted by the designated team and the release managers, you will be asked to merge your work into the main development line. + +The merge may have unintended interactions with other PLIPs coming in. +During the merge phase you must be prepared to help out with all the features and bugs that arise. + +If all went as planned, the next Plone release will carry on with your PLIP in it. +You'll be expected to help out with that feature after it's been released (within reason). diff --git a/coredev/release.md b/docs/contributing/core/release.md similarity index 54% rename from coredev/release.md rename to docs/contributing/core/release.md index 0d6ad6c57..723fb9cc4 100644 --- a/coredev/release.md +++ b/docs/contributing/core/release.md @@ -11,13 +11,12 @@ myst: This chapter describes the process to release Plone and its packages. - ## Release process for Plone packages To keep the Plone software stack maintainable, the Python egg release process must be automated to a high degree. This happens by enforcing Python packaging best practices, and then making automated releases using [`zest.releaser`](https://github.com/zestsoftware/zest.releaser/). -This is extended with Plone coredev specific features by [`plone.releaser`](https://github.com/plone/plone.releaser). +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. @@ -29,12 +28,12 @@ All files mentioned in this list may be written in Markdown or reStructuredText - 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` (or {file}`docs/HISTORY`) must be always up-to-date and must contain list of functional changes which may affect package users. - {file}`CHANGES` must contain release dates. - {file}`README` and {file}`CHANGES` must be visible on PyPI. - Released eggs must contain generated gettext `.mo` files, but these files must not be committed to the repository. The `.mo` files can be created with the `zest.pocompile` add-on, which should be installed together with `zest.releaser`. -- `.gitignore` and `MANIFEST.in` must reflect the files going in to the egg (must include page template, po files). +- `.gitignore` and `MANIFEST.in` must reflect the files going in to the package (must include page template and `.po` files). ```{seealso} [High quality automated package releases for Python with `zest.releaser`](https://opensourcehacker.com/2012/08/14/high-quality-automated-package-releases-for-python-with-zest-releaser/). @@ -44,46 +43,51 @@ All files mentioned in this list may be written in Markdown or reStructuredText ## Special packages The Plone Release Team releases the core Plone packages. -Several others also have the rights to release individual packages on [PyPI](https://pypi.org/). +Several other people also have the rights to release individual packages on [PyPI](https://pypi.org). If you have those rights on your account, you should feel free to make releases. Some packages need special care, or should be done only by specific people, as they know what they are doing. These are: `Products.CMFPlone`, `Plone`, and `plone.app.upgrade` -: Please leave these to the release manager, Eric Steele. +: Please leave these to the release managers, Eric Steele and Maurits van Rees. `plone.app.locales` -: Please leave this to the i18n team lead, Vincent Fretin. +: Please leave this to the i18n team lead, Mikel Larreategi `@erral`. +`plone.staticresources`, `mockup`, `plonetheme.barceloneta`, `plone.classicui`: +: Please leave this to the Classic UI team, especially Peter Mathis `@petschki`, Johannes Raggam `@thet`, and Maik Derstappen `@MrTango`. + +`plone.restapi` and `plone.volto`: +: Please leave these to Timo Stollenwerk `@tisto` or David Glick `@davisagli`. ## Plone core release process checklist 1. Check Jenkins status. - Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org/). + Check the latest Plone coredev job on [Jenkins](https://jenkins.plone.org). It should be green, but if it is not, fix the problem first. -2. Check out `buildout.coredev`. +1. Clone `buildout.coredev`, then check out and build the version to be released. ```shell git clone git@github.com:plone/buildout.coredev.git cd buildout.coredev - git checkout 5.1 - python bootstrap.py + git checkout 6.1 + ./bootstrap.sh bin/buildout -c buildout.cfg ``` -3. Check packages for updates. - Check all packages for updates, add to or remove from `checkouts.cfg` accordingly. +1. Check packages for updates. + Add to or remove from `checkouts.cfg` accordingly. This script may help: ```shell 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. +1. Check packages individually. Use the `bin/fullrelease` script from the core development buildout. This includes extra checks that we have added in `plone.releaser`. @@ -95,38 +99,38 @@ These are: 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. Run [pyroma](https://pypi.org/project/pyroma/). + 1. Run [check-manifest](https://pypi.org/project/check-manifest/). + 1. Check package "best practices" (`README`, `CHANGES`, `src` directory). + 1. Check if the version in `setup.py` is correct and follows our versioning best practice. + 1. Make a release with `zest.releaser`: `bin/fullrelease`. + 1. Remove packages from the `auto-checkout` section in `checkouts.cfg`, and update `versions.cfg`. + +1. Make sure `plone.app.upgrade` contains an upgrade step for the future Plone release. +1. Update CMFPlone version in `profiles/default/metadata.xml`. +1. Create an issue in https://github.com/collective/plone.app.locales/issues to ask the i18n team lead `@erral` to do a `plone.app.locales` release. +1. Create a pending release (directory) on [dist.plone.org](https://dist.plone.org/). + 1. Copy all core packages there. - 2. Possibly make an alpha or beta release of CMFPlone. - 3. Copy the `versions.cfg` file from coredev to there. + 1. Possibly make an alpha or beta release of CMFPlone. + 1. Copy the `versions.cfg` file from coredev to there. -9. Write an email to the Plone developers list announcing a pending release. -10. Update `plone.app.locales` version. -11. Create a unified changelog. +1. Write an email to the Plone developers list announcing a pending release. +1. Create a post on the Plone Community Forum announcing a pending release. +1. Update `plone.app.locales` version. +1. Create a unified changelog. ```shell bin/manage changelog ``` -12. Make the final release on dist.plone.org (remove "-pending") -13. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). -14. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). -15. Create a release page on [plone.org](https://plone.org/download/releases) -16. Send links to the installers list at plone-installers@lists.sourceforge.net. -17. Wait for installers to be uploaded to Launchpad, with a link to the plone.org release page. -18. Publish release page on plone.org. -19. Update plone.org homepage links to point to the new release. -20. Send out announcement to the plone-announce email distribution list. -21. Update #plone topic (obsolete? maybe announce to Discord?) -22. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. +1. Make the final release on [dist.plone.org](https://dist.plone.org/) (remove "-pending") +1. Update the "-latest" link on [dist.plone.org](https://dist.plone.org/). +1. For Plone 5.x versions only, create the new release on [Launchpad](https://launchpad.net/plone/). +1. Create a release page on [plone.org](https://plone.org/download/releases) +1. Wait for installers to be uploaded to Launchpad, with a link to the [plone.org](https://plone.org/download/releases) release page. +1. Publish release page on [plone.org](https://plone.org/). +1. Update [plone.org](https://plone.org/) homepage links to point to the new release. +1. Send out announcement to the plone-announce email distribution list for the final release. +1. Create a post on the Plone Community Forum announcing the final release. +1. Ask the security team to update the [Hotfixes](https://plone.org/security/hotfixes/) page in the configuration control panel. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 24be3d4ff..54735e7e7 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -20,7 +20,6 @@ To contribute to any project in Plone, you must follow the policies of the [Plon This chapter covers policies that apply to all Plone projects. Other chapters cover any variations and additional policies for each project. - (contributing-sign-and-return-the-plone-contributor-agreement-label)= ## Sign and return the Plone Contributor Agreement @@ -48,7 +47,6 @@ Sign the Plone Contributor Agreement - [Plone Framework Components Relicensing Policy, Framework Components Available Under a BSD License](https://plone.org/foundation/about/materials/foundation-resolutions/plone-framework-components-relicensing-policy#3b050ad2-361a-46de-b5c6-9b90f8947eb7) ``` - (contributing-code-of-conduct-label)= ## Code of Conduct @@ -56,14 +54,12 @@ Sign the Plone Contributor Agreement The Plone Foundation has published a [Code of Conduct](https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct). All contributors to the Plone Documentation follow the Code of Conduct. - (contributing-first-time-contributors-label)= ## First-time contributors First-time contributors should read and follow our guide {doc}`first-time`. - (contributing-continuous-integration-label)= ## Continuous integration @@ -72,7 +68,6 @@ Plone project repositories use continuous integration (CI) to run tests, ensure Plone uses GitHub Actions, Jenkins, Cypress, Netlify, and other services for CI. All of a project's CI jobs must pass before a contribution may be accepted. - (contributing-change-log-label)= ## Change log entry @@ -93,18 +88,18 @@ When making a change to its documentation, set up, continuous integration, or ot The change log entry's format must be `###.type`, where `###` is the referenced GitHub issue or pull request number, `.` is the literal extension delimiter, and `type` is one of the following strings. -- `breaking` for breaking changes -- `bugfix` for bug fixes -- `documentation` for documentation -- `feature` for new features -- `internal` for internal changes +- `breaking` for breaking changes +- `bugfix` for bug fixes +- `documentation` for documentation +- `feature` for new features +- `internal` for internal changes A package configures the types it allows in a file `towncrier.toml` located at the root of its package directory. The content of this file must include the following. -- A brief message that summarizes the changes in your contribution. -- An attribution to yourself, in the format of `@github_username`. +- A brief message that summarizes the changes in your contribution. +- An attribution to yourself, in the format of `@github_username`. ```{important} These change log entries become narrative documentation. @@ -112,13 +107,13 @@ These change log entries become narrative documentation. You can write good change log entries with the following guidance. -- Use a narrative format, in the past tense, proper English spelling and grammar, and inline markup as needed. -- Write your change log entry for its appropriate audience. - - Most entries should address _users_ of the software. - - An entry for a change to a public API should address _developers_. -- If you fix a bug, write what was broken and is now fixed. -- If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it. -- Refer to narrative documentation as needed. +- Use a narrative format, in the past tense, proper English spelling and grammar, and inline markup as needed. +- Write your change log entry for its appropriate audience. + - Most entries should address _users_ of the software. + - An entry for a change to a public API should address _developers_. +- If you fix a bug, write what was broken and is now fixed. +- If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it. +- Refer to narrative documentation as needed. The following text is an example of a good change log entry, placed inside {file}`/news/4470.documentation`. @@ -132,7 +127,6 @@ The following would be a poor change log entry. Fix #123456 by chaning config of additionalToolbarComponents [did_not_read_this_guide] ``` - (contributing-project-configuration-files-label)= ## Project configuration files @@ -141,7 +135,6 @@ To standarize the developer experience across packages, a configuration tool is See the [tool documentation](https://github.com/plone/meta) for more information. - (contributing-specific-contribution-policies-for-projects-label)= ## Specific contribution policies of projects @@ -171,7 +164,6 @@ Volto : Plone 6 default frontend. See {doc}`../volto/contributing/index`. - (contributing-releases-label)= ## Releases @@ -182,7 +174,6 @@ We use [`zest.releaser`](https://zestreleaser.readthedocs.io/en/latest/) for rel We use [`release-it`](https://github.com/release-it/release-it) for releasing the Node.js packages used in Plone, including {doc}`Volto ` and the [Classic UI mockup](https://github.com/plone/mockup). - ```{toctree} --- caption: Contributing @@ -192,6 +183,7 @@ hidden: true first-time documentation/index +core/index plone-api plone-restapi volto diff --git a/docs/glossary.md b/docs/glossary.md index 4e161d317..bf30a43de 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -77,7 +77,7 @@ pipx pyenv Python version management. - [pyenv](https://github.com/pyenv/pyenv) lets you easily switch between multiple versions of Python. + [pyenv](https://github.com/pyenv/pyenv) lets you easily switch between multiple versions of Python. pm2 [PM2](https://pm2.keymetrics.io/) is a daemon process manager. @@ -470,6 +470,10 @@ language tag - W3C Working Draft [Language Tags and Locale Identifiers for the World Wide Web](https://www.w3.org/TR/ltli/) ``` +lxml + A library used for processing XML and HTML with Python. It is a binding for the libxml2 and libxslt C libraries. + See https://lxml.de/ + gettext UNIX standard software translation tool. See https://www.gnu.org/software/gettext/. @@ -673,6 +677,9 @@ UID UID is an acronym meaning "unique identifier". A UID is an identifier that is guaranteed to be unique among all identifiers used for those objects and for a specific purpose. +pdb + The Python Debugger module is an interactive source code debugger for Python programs. See https://docs.python.org/3/library/pdb.html + integer identifier intid In Plone, an integer identifier, or intid, is used to uniquely identify content objects within a Plone site. @@ -741,7 +748,7 @@ Plone frontend TLS Transport Layer Security Transport Layer Security (TLS) is a cryptographic protocol designed to provide communications security over a computer network. - + ```{seealso} [Transport Layer Security](https://developer.mozilla.org/en-US/docs/Web/Security/Transport_Layer_Security) article from MDN. ``` diff --git a/requirements.txt b/requirements.txt index a6c516054..a0d60d48f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -23,4 +23,5 @@ sphinxcontrib-qthelp==1.0.3 # https://github.com/plone/documentation/issues/160 sphinxcontrib-serializinghtml==1.1.5 # https://github.com/plone/documentation/issues/1604 sphinxcontrib-video sphinxext-opengraph +sphinxcontrib.mermaid==0.9.2 vale==2.30.0 diff --git a/styles/Vocab/Plone/accept.txt b/styles/Vocab/Plone/accept.txt index 8d79192ed..45c67d02c 100644 --- a/styles/Vocab/Plone/accept.txt +++ b/styles/Vocab/Plone/accept.txt @@ -8,8 +8,10 @@ accessor APIs [Aa]sync [Bb]ackend +backport(ed|ing) Barceloneta [Bb]oolean +bugfix buildout cacheable CommonJS @@ -18,11 +20,14 @@ folderish fieldset getter JavaScript +[Jj]enkins jQuery +libxslt Mockup npm nvm Pastanaga +PLIP(s) Plone pluggab(le|ility) programatically @@ -35,6 +40,7 @@ RichText Sass Schuko subfolder +[Tt]owncrier transpile[dr]{0,1} unregister UUID