We're going to be adjusting how we handle Git going forward, this includes commit messages, PRs, and general workflow.
Our current model
Each repository has 2 branches:
PRs are made from Development to Main once the Program is ready for stable release
- There is no particular schema for commit messages or PR titles/descriptions
- PRs can be as large and add/change as many things as the PR opener wants
- PRs can be force-merged by repository admins
PKGBUILDs pull the Main branch and build it whenever called
Pros:
- We don't build PKGBUILDs of unstable releases by accident (Main and Development are split)
- That's pretty much it
Cons:
This is unintuitive for many potential contributors already acquainted with Git
Repository admins being able to force-merge branches without any review can lead to a few issues:
- Anti-patterns can slip through without review
- Broken code may accidentally be merged to main, making PKGBUILDs fail
PRs can get too large to manage, introducing too many things. One feature may be a good idea, one may be a terrible idea.
There is virtually no form or structure for new contributors to look over and follow
Proposed Model
I propose an alternative model, that follows a feature-based Git workflow and has proper standards to follow when merging / committing:
- Drop the Development branch entirely, stable releases will be tagged from Main
Every time you add a new feature or patch a bug/fix an issue, open up a new branch and then PR that branch against main. The PR should include:
- A log of what has been changed in the PR
- A reasonably detailed description regarding why these changes are appropriate/necessary
- A distinguishable and imperative title
PRs are to be rebased and merged to avoid polluting the Git history
PKGBUILDs will be updated to pull specific tags from each Git repository, ensuring reproducibility
Repository admins will no longer be able to force-merge. All merges must be appropriately reviewed
All commits shall be written in the imperative sense for easier readability and more clarification on what work was done in each commit. For example:
- Fix bug with package sorting algorithm
- Update Cargo lockfile
- Rework list_disks.py
Commits shall be reasonably split, please make sure you don't accidentally change 23 files with 1000 additions and 678 deletions in a commit labelled "Rework program"
Working Example: Sally would like to fix Issue #23 on foo-bar
Sally checks out a new branch
Sally then implements a fix for Issue #23 and pushes it to a new upstream branch
git push -u origin fix-23.
Sally opens a PR from fix-23 -> Main, detailing what she changed and how this will improve foo-bar
This is subsequently tested, worked on, and merged without disrupting anyone else's work and/or branches
John, the repository owner, is happy with this, and tags it as a release
John then pushes the newly created tag to upstream
Michal, the self-insert packaging team member, then sees that John has released a new tag 1.4.1 on foo-bar, and knowing that this is confirmed a stable release, updates the PKGBUILD accordingly.
Pros
- No one's workflow is disrupted
- All packages build from a stable, defined and reproducible git tag
- Every PR is thoroughly tested and reviewed before merging
Cons
- There's kind of a reason most developers do this
