WIP - Integrate buildoutcoredevdocs

coredev/agreement.md

@@ -7,6 +7,10 @@ myst:
     "keywords": "Contributing, Plone"
 ---
 
+```{todo}
+All this can go, it's redundant
+```
+
 (contributing-to-plone-label)=
 
 # Contributing to Plone
@@ -19,27 +23,27 @@ Sending in a contributors agreement does not guarantee your commit access to the
 
 We ask that before requesting core access you familiarize yourself a little with the community since they will help you get ramped up:
 
--   Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat <culture>` with a focus on getting to know the active developers a bit.
+- Ask and (especially) answer questions on [the Plone forum](https://community.plone.org/) and in {doc}`Plone chat <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).
+- Attend a [conference](https://plone.org/news-and-events/events/plone-conferences), [symposium](https://plone.org/news-and-events/events/regional), or participate in a [sprint](https://plone.org/news-and-events/events/sprints).
 
     There are plenty of opportunities to meet the community and start contributing through various coding sessions, either in person or on the web.
 
     You may even be able to get immediate core access at a conference if you are flexing your mad coding skills and the right people are attending.
 
--   Get your feet wet by contributing to the [collective](https://collective.github.io/).
+- Get your feet wet by contributing to the [collective](https://collective.github.io/).
     Don't worry about getting it perfect or asking for help.
     This way you get to know us and we improve our code together as a community.
 
--   **Patches:** Historically we encouraged people to submit patches to the ticket collector.
+- **Patches:** Historically we encouraged people to submit patches to the ticket collector.
     These tickets are usually ignored forever.
     Technically, for us to accept your patch, you must sign the contributors agreement.
     If you want to contribute fixes, please just sign the agreement and go through the standard GitHub pull request process described below until you feel comfortable to bypass review.
     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 <agreements@plone.org>.
+- 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 <agreements@plone.org>.
     This offers both copyright protection and ensures that the Plone Foundation is able to exercise some control over the codebase, ensuring it is not appropriated for someone's unethical purposes.
     For questions about why the agreement is required, please see [About the Plone Contributor Agreement
 ](https://plone.org/foundation/contributors-agreement).
@@ -50,14 +54,13 @@ A common way to start contributing is to participate in a [Plone sprint](https:/
 
 **Welcome to the Plone community!**
 
-
 ## Dealing with pull requests on GitHub
 
 Before we can merge a pull request, we must ensure that the author has signed the Plone Contributor Agreement.
 
 If they're listed in either the [Developers](https://github.com/orgs/plone/teams/developers/members) or [Contributors](https://github.com/orgs/plone/teams/contributors/members) team, the author has signed the Plone Contributor Agreement, so we can go ahead and merge.
 
 If they aren't listed there, they may have signed and returned the Plone Contributor Agreement, but they were not yet added to a team.
-You can ask agreements@plone.org to verify.
+You can ask <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.

coredev/continous-integration.md

@@ -7,6 +7,10 @@ myst:
     "keywords": "Plone, continuous integration, best practices"
 ---
 
+```{todo}
+needs redaction and upgrade
+```
+
 # Essential continuous integration practices
 
 The CI system at [jenkins.plone.org](https://jenkins.plone.org) is a shared resource for Plone core developers to notify them of regressions in Plone core code.
@@ -15,7 +19,6 @@ Build breakages are a normal and expected part of the development process.
 Our aim is to find errors and eliminate them as quickly as possible, without expecting perfection and zero errors.
 Though, there are some essential rules that needs to be followed in order to achieve a stable build.
 
-
 ## 1) Don't check in on a broken build
 
 Do not make things more complicated for the developer who is responsible for breaking the build.
@@ -34,7 +37,6 @@ If this is the case, there is no way around breaking a single build for a certai
 In this case run the all tests locally with all the changes and commit them within a time frame of ten minutes.
 ```
 
-
 ## 2) Always run all commit tests locally before committing
 
 Following this practice ensures the build stays green, and other developers can continue to work without breaking the first rule.
@@ -46,33 +48,28 @@ Furthermore, a common source of errors on check-in is to forget to add some file
 
 If you follow this rule and your local build passes, you can be sure that this is because someone else checked in in the meantime, or because you forgot to add a new class or configuration file that you have been working on into the version control system.
 
-
 ## 3) Wait for commit tests to pass before moving on
 
 Always monitor the build's progress, and fix the problem right away if it fails.
 You have a far better chance of fixing the build, if you just introduced a regression than later.
 Also another developer might have committed in the meantime (by breaking rule 1), making things more complicated for yours.
 
-
 ## 4) Never go home on a broken build
 
 Taking into account the first rule of CI ("Don't check in on a broken build"), breaking the build essentially stops all other developers from working on it.
 Therefore going home on a broken build (or even on a build that has not finished yet) is **not** acceptable.
 It will prevent all the other developers to stop working on the build or fixing the errors that you introduced.
 
-
 ## 5) Always be prepared to revert to the previous revision
 
 In order for the other developers to be able to work on the build, you should always be prepared to revert to the previous (passing) revision.
 
-
 ## 6) Time-box fixing before reverting
 
 When the build breaks on check-in, try to fix it for ten minutes.
 If, after ten minutes, you aren't finished with the solution, revert to the previous version from your version control system.
 This way you will allow other developers to continue to work.
 
-
 ## 7) Don't comment out failing tests
 
 Once you begin to enforce the previous rule, the result is often that developers start commenting out failing tests in order to get the build passing again as quick as possible.
@@ -83,7 +80,6 @@ This means that we either caused a regression, made assumptions that are no long
 
 You should always either fix the code (if a regression has been found), modify the test (if one of the assumptions has changed), or delete it (if the functionality under test no longer exists).
 
-
 ## 8) Take responsibility for all breakages that result from your changes
 
 If you commit a change and all the tests you wrote pass, but others break, the build is still broken.
@@ -97,7 +93,6 @@ If you think you hit such a test, try to fix it (better) or re-run the Jenkins j
 
 In any case the developer who made the commit is responsible to make it pass.
 
-
 ## Further Reading
 
 Those rules were taken from the excellent book "Continuous Delivery" by Jez Humble and David Farley (Addison Wesley), and have been adopted and rewritten for the Plone community.

coredev/contributors_agreement_explained.md

@@ -8,8 +8,7 @@ myst:
 ---
 
 ```{todo}
-All this content should be audited against the plone.org site, probably removed, and replaced with a link to the authorative content on plone.org.
-Duplicating content is a maintenance burden.
+All this can go, it's redundant
 ```
 
 # Contributor's Agreement for Plone explained
@@ -18,8 +17,7 @@ Prospective contributors to the Plone code base are required to sign a contribut
 
 This document explains the purposes of this, along with questions and answers about what this means.
 
-The Plone Contributor's Agreement can be found at https://plone.org/foundation/contributors-agreement.
-
+The Plone Contributor's Agreement can be found at <https://plone.org/foundation/contributors-agreement>.
 
 ## About the Plone Contributor Agreement
 
@@ -28,10 +26,9 @@ Prior to the Foundation, the intellectual property of Plone was jointly held by
 
 The community members who formed the Foundation felt that having the Foundation hold these rights provides several benefits:
 
-1.  **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious.
-2.  **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use.
-3.  **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone.
-
+1. **Minimizing confusion / maximizing business compatibility** -- Organizations considering adopting Plone have a simple answer for "Who owns this?", rather than a more complicated answer that might scare away the legally-cautious.
+2. **Trademark protection** -- By having the Foundation hold the trademarks and rights to the Plone branding assets, it can effectively protect these from unfair use.
+3. **Guarantee of future Open Source versions** -- The Foundation's contributor agreement ensures that there will **always** be an OSI-approved version of Plone.
 
 ## Questions and answers
 
@@ -95,7 +92,7 @@ How much would a non-GPL version of Plone cost?
 > Despite this, though, many large and excellent contributions—such as Archetypes—have been made, and the Foundation hopes that companies will continue to do so.
 > In any event, a company that purchases a non-GPL license (should such ever become available) is contributing financial resources to our community, which can be used to further develop, market, and protect the GPL version of Plone.
 
-- https://plone.org/foundation/contributors-agreement/agreement.pdf
-- https://github.com/collective
-- https://github.com/plone
+- <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

@@ -8,7 +8,7 @@ myst:
 ---
 
 ```{todo}
-This content is probably redundant and should be purged.
+All this can go, it's redundant
 ```
 
 # Plone developer culture

coredev/documentation.md

@@ -6,21 +6,22 @@ myst:
     "property=og:title": "Writing documentation of Plone"
     "keywords": "documentation, Plone"
 ---
+```{todo}
+shorten & update
+```
 
 # Writing documentation
 
 For general guidance for contributing documentation, see {doc}`contributing/index`.
 
 For documentation authors, see {doc}`contributing/authors`.
 
-
 ## Documentation of Plone
 
-The comprehensive resource for Plone documentation is https://6.docs.plone.org/.
+The comprehensive resource for Plone documentation is <https://6.docs.plone.org/>.
 The documentation repository is on [GitHub](https://github.com/plone/documentation).
 Information for how to contribute to documentation can be found at {doc}`contributing/index`.
 
-
 ## Documenting a package
 
 At the very least, your package should include the following forms of documentation.
@@ -33,48 +34,45 @@ It should be formatted using [GitHub flavored Markdown](https://github.github.co
 
 `README.md` should include:
 
--   A brief description of the package's purpose.
--   Installation information (How do I get it working?)
--   Compatibility information (what versions of Plone does it work with?)
--   Links to other sources of documentation.
--   Links to issue trackers, mailing lists, and other ways to get help.
-
+- A brief description of the package's purpose.
+- Installation information (How do I get it working?)
+- Compatibility information (what versions of Plone does it work with?)
+- Links to other sources of documentation.
+- Links to issue trackers, mailing lists, and other ways to get help.
 
 ### The manual (narrative documentation)
 
 The manual goes into further depth for people who want to know all about how to use the package.
 
 It includes topics like:
 
--   What are its features
--   How to use them (in English—not doctests!)
--   Information about architecture
--   Common gotchas
+- What are its features
+- How to use them (in English—not doctests!)
+- Information about architecture
+- Common gotchas
 
 The manual should consider various audiences who may need different types of information:
 
--   End users who use Plone for content editing, but don't manage the site.
--   Site administrators who install and configure the package.
--   Integrators who need to extend the functionality of the package in code.
--   System administrators who need to maintain the server running the software.
+- End users who use Plone for content editing, but don't manage the site.
+- Site administrators who install and configure the package.
+- Integrators who need to extend the functionality of the package in code.
+- System administrators who need to maintain the server running the software.
 
 Simple packages with limited functionality can get by with a single page of narrative documentation.
 In this case, it's simplest to include it in an extended `README.md`.
-Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching.
+Some excellent examples of a single-page README are <https://pypi.org/project/plone.outputfilters/> and <https://github.com/plone/plone.app.caching>.
 
 If your project is moderately complex, you may want to set up your documentation with multiple pages.
 The preferred way to do this is to add Sphinx to your project, and host your docs on readthedocs.org, so that it rebuilds the documentation whenever you push to GitHub.
 If you do this, your `README.md` must link off site to the documentation.
 
-
 ### Reference or API documentation
 
 An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code).
 It is meant for random access to remind the reader of how a particular class or method works, rather than for reading in its entirety.
 
 If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx.
 
-
 ### Changes or history
 
 ```{todo}
@@ -102,7 +100,6 @@ See <https://raw.github.com/plone/plone.app.caching/master/CHANGES.rst> for a fu
 
 If a change was related to a bug in the issue tracker, the changelog entry should include a link to that issue.
 
-
 ### Licenses
 
 Information about the open source license used for the package should be placed within the `docs` directory.