#+TITLE: Hyperdrive.el contributing guidelines

* Commit messages

We aren't terribly pedantic about them, but here are some guidelines we vaguely follow:

** Prefixes

We tend to prefix our commit messages with these keywords:

+ ~Add~ :: A commit that primarily adds a new feature or code to the program.
+ ~Change~ :: A commit that primarily changes program behavior in a way that isn't necessarily fixing a bug.
+ ~Fix~ :: A commit that primarily fixes a bug in the program.
+ ~Remove~ :: A commit that primarily removes code from the program (e.g. an obsolete option or compatibility code).
+ ~Docs~ :: A commit that only changes documentation (in the manual or docstrings).
+ ~Comment~ :: A commit that only affects comments in source code.  (We try to do these in commits separate from source code changes, especially when adding TODO-type items.)
+ ~Meta~ :: A commit that makes a change to files in the repository that aren't part of the program itself (e.g. ~.gitignore~, ~Makefile~, CI configuration).
+ ~Tidy~ :: A commit that only tidies up aesthetics, indentation, whitespace, typos, etc.  A ~Tidy~ commit should be intended to /never change program behavior/ (if it were later to be found to have done so, it could be reverted without negative consequences).
+ ~Limerick~ :: /When software makes you feel down, this commit can fix your frown; but read it, you must; or be turned to dust; no, wait, that's only haiku./
+ ~Revert~ :: A commit that reverts an earlier commit.
+ ~Merge~ :: A commit that merges a branch.  (Rather than the default git ~Merge branch 'foo'~, we describe simply what the branch changes, like any other commit.)
+ ~Release~ :: A commit that marks a new versioned release.  (Generally it should only change metadata, like a version number in various places.)

As well, sometimes two keywords might be used together if the lines between them seem blurred (e.g. ~Add/Change~).

* Release checklist

These checklists should be followed when releasing new versions:

** Commit new pre-release

   In ~master~ branch:

   1. [ ] Update package main file header version (adding ~-pre~ suffix).
   2. [ ] Update CHANGELOG.
   3. [ ] Rebuild .texi manual (see [[*Rebuilding the ~texi~ manual]]).
   4. [ ] Commit changes.

** Release new feature (or minor) version

   In ~master~ branch:

   1. [ ] Update package main file header version (removing ~-pre~ suffix).
   2. [ ] Update CHANGELOG (with release date and version).
   3. [ ] Update [[*Version number locations][Version number locations]] if necessary (e.g. if gateway version changes).
   4. [ ] Rebuild .texi manual (see [[*Rebuilding the ~texi~ manual]]).
   5. [ ] Commit changes.
   6. [ ] Merge ~master~ branch into ~stable~ branch.
   7. [ ] Make new git tag for new release (tagging the commit on ~stable~).
   8. [ ] Push ~master~ and ~stable~ branches to remote.
   9. [ ] Push git tags.
   10. [ ] [[*Commit new pre-release][Commit new pre-release]] before adding more changes.

** Release new bugfix version (when applying bug fixes to a stable release, not to ~master~)

   In ~stable~ branch:

   1. [ ] Update package main file header version (increment bugfix number (i.e. the third number), adding ~-pre~ suffix).
   2. [ ] Update ~CHANGELOG~ (without release date and with ~-pre~ suffix).
   3. [ ] Rebuild manual (see [[*Rebuilding the ~texi~ manual]]).
   4. [ ] Commit changes.
   5. [ ] Commit code/doc fixes and ~CHANGELOG~ updates.
   6. [ ] Update package main file header version (removing ~-pre~ suffix).
   7. [ ] Update ~CHANGELOG~ (with release date and version).
   8. [ ] Rebuild manual (see [[*Rebuilding the ~texi~ manual]]).
   9. [ ] Commit changes.
   10. [ ] Make new git tag for new release.
   11. [ ] Push ~stable~ branch to remote.
   12. [ ] Merge ~stable~ branch back to ~master~.
   13. [ ] Push ~master~ branch to remote.
   14. [ ] Push git tags.

* Version number locations

/A list of the places where version numbers are present and need to be updated./

** Gateway version numbers

+ [ ] [[file:hyperdrive.el::(defvar h/gateway-urls-and-hashes][h/gateway-urls-and-hashes variable]]
+ [ ] [[file:hyperdrive-vars.el::defvar h/gateway-version-expected "3.7.0"][h/gateway-version-expected variable]]

*** Getting ~sha256sum~ for each release of ~hyper-gateway-ushin~

- [[https://ci.codeberg.org/repos/13334][Codeberg Woodpecker CI]]
- [[https://git.sr.ht/~ushin/hyper-gateway-ushin/refs/][SourceHut refs page]]

* Rebuilding the ~texi~ manual

If you enable the [[*pre-commit hook][pre-commit hook]], the texi manual will rebuild
whenever you attempt to commit changes to ~doc/hyperdrive.org~.

To rebuild the texi manual without modifying the contents of
~doc/hyperdrive.org~ in order to, e.g., update the version number
listed in the manual when tagging a new release, in the project root,
run:

#+begin_src shell
touch doc/hyperdrive.org && make doc
#+end_src

* Git hooks

Please consider using the following git hooks:

** pre-commit hook

[[file:tracked-hooks/pre-commit]]

This ~pre-commit~ hook helps ensure that the ~hyperdrive.texi~ is
rebuilt and committed at the same time as ~hyperdrive.org~. It
rebuilds ~.texi~ whenever ~.org~ is about to be committed, and it
prevents ~.org~ from being committed while ~.texi~ has unstaged
changes.
