These are team practices that we try to follow across all repositories of jupyter-book.
They are not strictly enforced, but we ask that you prioritize following them, and provide a clear rationale if you don’t intend to.
When to merge pull requests¶
We want to encourage fluid contributions and a bias towards action. While we care a great deal about the quality of our code, we believe that rapid iteration is a better mechanism for building good software, rather than having to get it perfect on the first attempt. We aim for optimistic merges, with core-team contributors using their best judgement to determine whether a change needs wider input. Here are a few guidelines to follow:
Aim to merge only changes you understand fully, if not seek review from the rest of the team.
Use the
#developmentchannel in Discord to ask questions. That’s a useful place to signal-boost questions and discussion.Smaller, iterative changes: are low risk - aim to seek feedback, but don’t block yourself if you’re not getting a response!
Examples: targeted bug fixes, typos, docs changes.
Larger changes for maintainers or users: more important to get review - seek input and post messages in both GitHub and Discord.
Examples: An AST change, a change to core processing infrastructure, a change to team practices everybody will need to follow, a new directive, a breaking change for users we can’t easily walk back.
Use the GitHub UI to review your own pull request! If you’d like to merge without another person reviewing first, this is a helpful way to show you’ve done some due-diligence.
In general, we trust those with merge rights to make the right decision. You should use your best judgment and it’s OK if you make a mistake - we can always revert changes if it’s necessary.
Share notes and materials in our team drive¶
We use a shared Google Drive to make it easier for us to re-use the same content, and to have shared spaces for notes. We encourage you to use this space to facilitate collaboration and sharing!
When merging PRs, use squash commits¶
When you merge a pull request, use Squash Commits before merging.