Developer: Git Structure and Workflow

This page is primarily for developers that have write access to the hpn-ssh repo on github.

Structure:

There are 4 persistent branches:

1. master - this is the release branch. No development takes place in this branch. Updates to this branch are only allowed from reviewed and approved pull requests. Generally speaking, all pull requests are made against the release_candidates branch. Different versions of hpn-ssh are identified through tags.
2. release_candidates - this branch is a staging branch to allow the community to inspect and comment on proposed releases. Updates to this branch are only allowed from reviewed and approved pull requests. These requests are generally made against either dev_major or dev_minor.
3. dev_major - this branch is used for major changes in the functionality, usage, or performance of HPN-SSH that were developed in house. For example, this would include the introduction of new cipher implementations, changes to binary nomenclature, and similar highly impactful changes. Authorized developers can merge development branches into dev_major without review.
4. dev_minor - this branch is generally used for incorporating new versions of OpenSSH. However, it can also be used by HPN-SSH for bugfixes, security fixes, minor changes to the code base that do not significantly alter functionality, and so forth. For example, a modification to the parallelized ChaCha20-Poly1305 that reduces memory usage or optimizes an aspect of the implementation would use this branch. Authorized developers can merge development branches into dev_minor without review.

Note: Developers must ensure that dev_major and dev_minor branches are synched to master before they merge branches that will increment the version number. If necessary, dev_minor and dev_major can be deleted and recreated from master if they become terminally out of synch.

Development branches:

These branches are generally not persistent and are used to develop new features, functionality, porting OpenSSH releases, and fixes. Nomenclature for these branches is, largely, up to the developer but guidelines recommend the following.

port_[OpenSSH Release]_[HPN-SSH Release]: This is used when merging new OpenSSH releases into HPN-SSH. For example, when porting OpenSSH 9.7 into HPN-SSH 18.3.1 a branch called port_9.7.0_18.4.0 was used.

bug_version_bug-name: This would be for big fixes including security fixes. For example, bug_18.3.0_xor-segfault would be for a bug causing segfaults in the xor function in HPN-SSH version 18.3.0

fix_version_fix-name: This would be for optimizations, non-impactful bugs, and other minor changes to the code base. For example, fix_18.3.0_double_dereference would be to remove an unnecessary double dereference from a function.

feature_version_feature-name: This would be for the development of new features, functionality, or major optimizations. For example, feature_18.4.0_parallel-gcm would be for the development of a parallel AES-GCM implementation.

Note: Developers may append their initials to the end of the branch name if they so desire.

Note: Ephemeral branches do not necessarily have to abide by these naming conventions, but it is strong encouraged. This is especially true for branches that will enter the promotion workflow.

Note: Ephemeral branches should be deleted by the author when it is no longer needed.

Workflow:

for minor releases: development branch -> dev_minor -> [PR] -> release_candidates -> [PR] -> master

for major releases: development branch -> dev_major -> [PR] -> release_candidates -> [PR] -> master

For critical/security bugs: development branch -> dev_minor -> [PR] -> master

Note: A [PR] implies that the commit successfully passed all CI tests on github. If an individual test does not pass, a commit may still be promoted if the developer can provide a rational reason as to why this failed test is not indicative of a true bug.