Merge pull request plone#1435 from plone/add-buildout.coredev-docs

Converted rst to MyST from plone/buildout.coredev

Author: stevepiercy

coredev/agreement.md

@@ -0,0 +1,64 @@
+---
+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  <https://github.com/plone>, 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 <culture>` 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 <https://plone.org/foundation/contributors-agreement/agreement.pdf>, then either send by postal mail to the address provided, or scan and email it to <[email protected]>.
+    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 have to check that the author has signed the contributor's agreement.
+
+If they're listed in <https://github.com/orgs/plone/teams/developers/members>, the author has signed so we can go ahead and merge.
+
+If they aren't listed there, there's still a chance they have signed the contributor's agreement.
+
+If they have signed before the move to GitHub, you can ask <[email protected]> to check.
+
+Pull requests without contributor's agreement can only be merged in trivial cases, and only by the release manager.

coredev/continous-integration.md

@@ -0,0 +1,105 @@
+---
+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.

coredev/contributors_agreement_explained.md

@@ -0,0 +1,101 @@
+---
+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)

coredev/culture.md

@@ -0,0 +1,30 @@
+---
+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.