Add the PR workflow to the team process docs in team compass

[bsipocz]

I noticed that there are features pushed directly into the main branch of repos that points to the need of spelling out that development should be done via pull requests (or spelt out that it's OK to directly push; which I strongly oppose if the project is to position itself as a community project).

I would also advocate for the fork based workflow as it both 1) keeps the main repo clear of random and often obsolte feature branches 2) more importantly it communicates that everyone in the community is on the same page and follows the same development process independently if they have write access or not. Not following the same process very much othering those without write access that they are not first-class citizens.

---

Things to document:

Proposing a change

• For any contributions to a project in the jupyter-book organization
• Fork the repository
• Implement the change in a branch on your fork
• Make a pull request against this branch into main of the repository.

Things that will make your PR more likely to be reviewed and merged

• It is tightly-scoped: Try to keep your diff to the simplest possible change needed to achieve the outcome you want.
• It links to an issue: Link the PR to an issue where the "what" and "why" for the change has already been discussed and agreed to resolve. If there is no issue, make sure the body of the PR explains why it is needed, and the summary of your change.
• It adds a test and documentation: These make the PR easier to trust and faster to review.

Don't forget that every pull request is a request for the valuable time of maintainers. Be respectful of and remember that this is a volunteer project without dedicated capacity.

[choldgraf]

My feeling is that this is a good idea to document, though we should enforce this more strongly on the core repositories (mystmd etc) rather than all repositories (eg myst-plugind or repositories that are more experimental).

I think what you're suggesting is something like:

The process for making changes is

• (usually) ensure there is an issue describing why a change should be made
• create a fork of the repository
• make your change in a branch in your fork
• make a pull request and reference any relevant issues

That said, I do generally prefer a "use your best judgement" over strict rules. Eg sometimes it is helpful to be able to push to main as a maintainer (eg to clean up releases if you missed something little that is a lot of toil to go through a full PR workflow)

[bsipocz]

push to main as a maintainer

Yes, I fully agree, but this case it was a new feature and not release related or dumpster fire resolving maintenance commits.

And IMO this should be done for the small repos as this is team rather than repo practice -- and bonus benefit would be that no repo would start messy and then as evolves trying to enforce rules but the rules are in place from the beginning. In my experience (not here, but in a different community where almost everyone has write access) it is much difficult to switch and enforce legacy contributors to change their process even if they are willing to follow the fork based ones elsewhere.