diff --git a/how-we-work/admin.qmd b/how-we-work/admin.qmd index 7cd1766..3332e0e 100644 --- a/how-we-work/admin.qmd +++ b/how-we-work/admin.qmd @@ -25,15 +25,17 @@ someone else has taken those admin responsibilities. Whenever a new GitHub repo is created for a new website or software project, run our custom command from our -[spaid](https://github.com/seedcase-project/spaid) toolkit (which -will need to be installed to use it) to set our custom repository settings. See that repo for more details. +[spaid](https://github.com/seedcase-project/spaid) toolkit (which will +need to be installed to use it) to set our custom repository settings. +See that repo for more details. ## Creating a GitHub repo from a local one If a local repository exists and a GitHub repository needs to be created for that repository, run our custom command from our -[spaid](https://github.com/seedcase-project/spaid) toolkit (which -will need to be installed to use it) to create the repo. See the spaid repo for more details. +[spaid](https://github.com/seedcase-project/spaid) toolkit (which will +need to be installed to use it) to create the repo. See the spaid repo +for more details. ## Merging topic branches @@ -54,9 +56,18 @@ general guidelines: - **Rebase:** Commits or PRs that have `build` and `chore` types as well as `sync` scopes (which usually fall under `chore` type) -- **Merge:** Non-atomic/other PRs (or if the PR title starts with `chore: :twisted_rightwards_arrows:`) +- **Merge:** Non-atomic/other PRs (or if the PR title starts with + `chore: :twisted_rightwards_arrows:`) By atomic PRs, we mean PRs that only include "self-contained changes" that are independent and fully functional on their own. E.g., a single feature and the accompanying tests or a bug fix. This way, if we accidentally introduced a bug, it would be easy to reverse that change. + +For PRs that are stacked, follow these steps: + +- Do not squash merge the base PR. Wait until all stacked PRs have + been approved. +- After each stacked PR has been approved, rebase all of them onto the + base PR. +- Finally, squash merge the base PR. diff --git a/how-we-work/workflow.qmd b/how-we-work/workflow.qmd index 7104a7b..f92d445 100644 --- a/how-we-work/workflow.qmd +++ b/how-we-work/workflow.qmd @@ -25,13 +25,30 @@ guidelines: - After creating a pull request, add it to the relevant GitHub Project since this is where we keep an overview of what each of us is currently working on. -- As you work on your branch and it starts growing too large in scope - and size, strongly consider creating "stacked pull requests" by - making a new branch on your current working branch and submit a new - pull request on top of the parent pull request branch. - In the pull request description, try to explain *why* you made the changes in the pull request, rather than the *what*. +If your task is too large in scope, modifies or adds many new files, or +has several complicated pieces, *strongly* consider making "stacked pull +requests". A stacked pull request is a pull request that is made on top +of another pull request. This way, you can separate the changes into +smaller, more manageable pieces that can be reviewed more easily and +quickly since larger pull requests take longer and are more difficult to +review. When making Stacked pull requests, follow these general +guidelines: + +- When making the first, base pull request, write in the description + that this will be a stacked pull request so that no one should merge + it, only until all the stacked pull requests are ready. +- As each stacked pull request is ready for review, team members will + review and make suggestions as needed. As the author, you'll need to + make sure all suggestions are merged downstream to the later pull + requests by rebasing. +- Once all stacked pull requests are reviewed and approved, they will + all be rebased onto the base pull request before being finally + squashed into the base pull request. This way, the base pull request + will contain all the changes from the stacked pull requests. + ::: callout-tip ### Creating conventional branches using the VS Code extension