diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..723ef36 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea \ No newline at end of file diff --git a/pull-requests.md b/pull-requests.md new file mode 100644 index 0000000..3179afc --- /dev/null +++ b/pull-requests.md @@ -0,0 +1,59 @@ +# Pull requests (PR) + +## Aims + + - Keep PRs small and/or easy for reviewers to understand. + - Keep PRs focused on one core issue. + - Get changes that might affect other features being developed onto + main in a timely fashion. + - Avoid blocking where one PR can’t be merged because it requires features that are being + developed on another branch that hasn’t been merged yet. + - Improve situational awareness of each other’s work and encourage early feedback. + +## Small features or changes: single PR + +Small features or changes should be proposed using a single PR, which details the +problem being addressed or the enhancement made, what is being done and why. A good rule of thumb is +that if the work for the PR has only taken a couple of sessions or days, then it’s best +just to propose via a single PR. + +## Large features or changes: single PR + +Sometimes you might want to propose large changes that you have developed quickly, +for example, using AI. In this case, it is fine and preferred to use a single PR. However, +you should be considerate of the impact on reviewers. Please consider: + + - Are your changes adequately explained in the PR description? + - Are the changes expected by the development team? If you are an external + contributor, consider raising an issue before the PR to consult maintainers. + - For AI-assisted contributions, a good guide is that the human effort involved in + opening the PR should exceed the expected effort of maintainers to review the PR. + - How else could you help reviewers digest the PR? + +***If the work is taking weeks, and the visibility of the changes you have in the +pipeline could be important for other developers, please use a +[multiple PR](#large-features-or-changes-multiple-prs) approach.*** + +## Large features or changes: multiple PRs + +Large features developed over multiple weeks should usually use multiple PRs. It +makes it easier for reviewers to digest the changes, and improves visibility of what’s +in the pipeline. A multiple PR approach typically takes the following form: + + - Before starting coding, create an issue describing the proposed changes to provide + visibility to other developers and provide a place for early discussion on the + proposed changes. + - Propose your changes incrementally across multiple PRs, with a single PR chunk + containing roughly no more than a week of coding effort. Use your judgment and chunk + the work in a logical fashion that fits your circumstances. The main thing is to + avoid dumping large PRs on other developers when they could have been provided the + changes in incremental chunks. + - Each PR should reference the original issue, and the last PR should close the + issue. + - If the new code in a chunk isn’t fully complete, hide it behind a feature flag, + an if-statement that prevents it from running unless a flag explicitly allows it + to do so. Add your new flag to feature_flag.yaml with a default value of False. + - The last PR for a new feature, once it is fully tested, should remove all the + feature-flag if-statements and the feature flag from the YAML file. ***Note, more + docs on setting up feature flags to be added once the first one is implemented.*** +