-
-
Notifications
You must be signed in to change notification settings - Fork 153
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
integrate coredev.buildout (was PR #1670) #1671
Merged
Merged
Changes from 71 commits
Commits
Show all changes
79 commits
Select commit
Hold shift + click to select a range
3c547df
Clean up PR #1670
stevepiercy 83b708f
Revert whitespace changes and use naked URLs (< and > are not require…
stevepiercy 6449526
Minor grammar fixes, restore whitespace, one line per sentence, empha…
stevepiercy 7d90a29
Revise documentation.md with current resources
stevepiercy e2fb4f8
- Set the stage for the purpose of this contributing how to guide. It…
stevepiercy e719f68
Pull in RTD PR review config
stevepiercy 1387142
Use correct primary branch
stevepiercy 717ea4a
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy 5124144
bin/wsgi no workie
stevepiercy ef84d05
Update commit message
stevepiercy b3f2347
Update mrdeveloper.md
stevepiercy 6f92024
Update package-dependencies.md, reverting whitespace changes
stevepiercy 57cd6fd
Revert whitespace changes, restore TODO
stevepiercy e626b65
Revert whitespace muckery
stevepiercy 9a98df4
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy a79fe1f
Revise and make recommendations in plips.md to remove coaching and fo…
stevepiercy ea65b7c
Move FAQ to the end to elevate the process overview.
stevepiercy d1b54fc
Fix linkcheck redirect
stevepiercy aa5a028
Revise how to submit a PLIP for today
stevepiercy 21453a6
Fix redirect
stevepiercy ef40380
Update pre-requisites of libx* and C compiler
stevepiercy cbb149e
Add admonition for non-3.11 Pythons
stevepiercy 962a4b9
Revise and make recommendations in plips.md to remove coaching and fo…
stevepiercy edee66e
Back off from attempt to use buildout for Volto, and refer to officia…
stevepiercy 7e45ba7
Use correct git terms, instead of gitterish
stevepiercy 0897e15
Give better instructions not to switch between Plone or coredev.build…
stevepiercy 1704bbc
Move new development branch under Edit packages, and use what @thet a…
stevepiercy 7e604ed
Add -N flag option to buildout
stevepiercy fcdd992
Reference tests to use PR, CI, and Jenkins first, and locally only if…
stevepiercy 7838b17
Add note for how to identify towncrier repos
stevepiercy abf5f7b
Remove obsolete section "Update `checkouts.cfg`"
stevepiercy bc12737
Copy from first-time-contributors about Fixes #ISSUE-NUMBER
stevepiercy 6ef5c58
Purge obsolete explanation about what Jenkins runs
stevepiercy 21e3658
Update C compiler pre-requisites
stevepiercy a80c9cc
Reword seealso for `mr.developer`
stevepiercy 26da8cc
Rewrite adn simplify git pieces
stevepiercy 6f816ae
Indicate symbol
stevepiercy 4a269ca
Fix headings and meta information
stevepiercy c8edc3c
Remove todo
stevepiercy 86c1fca
- Align overview with sections of PLIP submittal process
stevepiercy 33156c3
- Purge FAQ as redundant and unused. No one asks questions about PLIP…
stevepiercy 3315905
Volto has its own contributing process, regardless of whether it is a…
stevepiercy f087267
Add intersphinx configuration for Plone 5 docs
stevepiercy 2098aa7
Finalize PLIP stuff
stevepiercy 340a0ae
Clean up release.md and add Community Forum posts
stevepiercy 693d026
Update troubleshooting.md
stevepiercy 2f86304
Reorder navigation
stevepiercy 438b8ef
Rename troubleshooting.md to troubleshoot.md
stevepiercy cd238fe
Replace @vincentfretin with @erral
stevepiercy b5426e8
Add link to active PLIPs GitHub project board.
stevepiercy 9df10b5
Update docs/contributing/core/index.md
stevepiercy be8c6ad
Fix doc link, grammar.
stevepiercy 62072af
Use chromedriver and ROBOT_BROWSER environment variable
stevepiercy a26ee56
We don't use `bootstrap.py`. Burn it with 🔥!
stevepiercy 0d213ac
s/egg/package
stevepiercy 7b19bcb
Add maintainers
stevepiercy 4c7badf
Add GitHub handles to humans
stevepiercy 75f782c
Restore @plone/framework-team GitHub handle
stevepiercy 004370b
s/FWT/designated team
stevepiercy 4c16ff2
Update tips submodules/plone.api submodules/volto
stevepiercy d78a2d3
Add a todo for the Steering Circle
stevepiercy 7e741c8
Add the PLIP to the PLIP project board
stevepiercy ad7dce1
Remove TODO for Steering Circle, as it is not a relevant body to revi…
stevepiercy add1c99
Add a todo for the Steering Circle
stevepiercy ca03c87
Add the PLIP to the PLIP project board
stevepiercy e5dae08
Remove TODO for Steering Circle, as it is not a relevant body to revi…
stevepiercy 291bb0a
Merge remote-tracking branch 'origin/integratel-coredev.buildout-2' i…
stevepiercy 113d9b3
Revert "Update tips submodules/plone.api submodules/volto"
stevepiercy c4f30b3
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy 667124b
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy cdc9174
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy 50f8fe1
Use `-s` for a package
stevepiercy 53e678b
Fix typo
stevepiercy fea2941
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy 21df2a7
Merge branch '6.0' into integratel-coredev.buildout-2
tisto 187b9c4
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy 12b06a0
Merge branch '6.0' into integratel-coredev.buildout-2
stevepiercy b4f87fa
Comment out continuous-integration and silence Sphinx warning
stevepiercy 73524a4
Purge coredev directory of now obsolete files
stevepiercy File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This whole page is outdated, it does not mention
mr.roboto
, GHA norplone/meta
which make almost all the rules described outdated.Sorry that it took me forever to react on the call to help on this PR 🙇🏾
I can do the update, should I push it directly to this branch? 🤔
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gforcada please create a PR against this branch for review. Do not push commits directly to this branch.
I'm not clear on which repositories
plone/meta
applies. From what I know, many repositories usemake
and nottox
, including Volto, plone.restapi, and Documentation. Until there is both agreement and implementation for a unified approach, I don't know whetherplone/meta
should be declared as authoritative for all projects under the Plone GitHub organization.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, thanks I will do that (the branch).
As for
plone/meta
ormake
, well, it's literally all but volto related packages that already useplone/meta
. There are a few that are missing (like CMFPlone) that I did not had the time to applyplone/meta
to it.But this documentation is meant for classic UI, or? 🤔 I meant I saw quite a few references that always branch to say "if you are doing volto then see ../volto"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This part of the documentation is intended for anything that is not Volto, which includes Classic UI, core add-ons, and other core packages.
There is also an effort with cookiecutter and mxdev, which is intended to replace buildout, at which point another rewrite of docs will need to take place.
I don't know how that reconciles with
plone/meta
. I just document what I understand.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
plone/meta
andmxdev
/cookiecutter
are orthogonal, at least I'm 100% sure withmxdev
, withcookiecutter
that depends on what's being done, of for which purpose is used 😓I've seen so many
cookieXX
repositories, that I'm no longer sure what one should use 🤷🏾but if the goal is to replace
zc.buildout
, thenplone/meta
has nothing to do with that and should be fine to document.Actually
plone/meta
has quite some exhaustive documentation on its own 😄There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gforcada even before your review and subsequent pull request, I had a lot of issues with this document. It never had a high-level review. I apologize for not bringing up my concerns earlier, but here they are now.
Once we have an idea of what we want to do, then we can rewrite this document to achieve that goal. I'd be happy to have a chat with you in real-time in Discord, or continue the conversation here.
For cookie*, the primary repo is https://github.com/plone/cookieplone. It uses templates found in https://github.com/plone/cookieplone-templates. I don't know whether that repo uses
plone/meta
itself, but its templates do.cookie* uses mxdev, as described in https://6.docs.plone.org/install/manage-add-ons-packages.html#manage-plone-backend-packages-with-mxdev.
Are these files
plone/meta
's documentation?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In reverse order 🙃
yes, that's the documentation for
plone/meta
oh nice, thanks for the cookie pointers, now it's a bit more clear to me, the (not to be answered and solved now) is how that works with mr.bob and bobtemplates.plone and all that ecosystem, or again, we have cookie* for volto and mr.bob for classic UI? 🤔
for this document, I would say that it's an explanation of how the CI system works, being the target audience newcomers.
With the links you provided (thanks!) I would say it could be linked from https://6.docs.plone.org/contributing/index.html#continuous-integration, then, we could simplify my PR to remove the explanation about PRs and be more focused only on the tooling involved.
How that sounds?
As for talking in discord, sure, this week, I do have time in European evenings, something like https://www.timeanddate.com/worldclock/converter.html?iso=20240708T170000&p1=37&p2=202 ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK on meta docs.
I encourage you to try cookieplone for fun. If there is something missing, or is not clear how to do, then file an issue.
I think an explanation page would be good. I do not know all the parts of CI, what each part does, or how they al work together to fulfill specified tasks.
In that context, let's change the document title to "Continuous integration". If we keep "essential" or "practices", then we start telling the reader how to do things or what things they should do, which makes it a how-to guide, not an explanation.
Also if you use Mermaid for diagrams, you could even draw a picture of the workflow.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@gforcada to get this PR merged, I will remove the CI stuff entirely. It's not correct and should not be published in its current state. The rest of it is good. We can add the CI stuff in another PR.
I'll work on pulling it out of this PR, and moving it back to the coredev directory to preserve the grammar and MyST work I did. I'll do that sometime this week.