Skip to content
This repository has been archived by the owner on Sep 27, 2023. It is now read-only.

Latest commit

 

History

History
143 lines (111 loc) · 5.18 KB

CONTRIBUTING.md

File metadata and controls

143 lines (111 loc) · 5.18 KB
Raw

Contributing

Building/Testing

$ nix develop;
$ make;
$ ls ./bin/;
resolver
$ make check;
...<SNIP>...

Building Docs

Docs are generated by Doxygen.

$ nix develop;
$ make doc;
$ firefox ./docs/index.html;

Making a Release

This project follows semantic version guidelines with then scheme <MAJOR>.<MINOR>.<PATCH>.

This means that when a release is created, the version number should be incremented using the following rules:

  • Bug Fixes and Optimizations which have no effect on the availability of public interfaces should increment patch version.
    • When users see that patch was incremented they expect to update resolver without making ANY changes to their existing usage.
    • If you didn't add any new features, and you didn't break existing tests, you should probably bump this.
  • New Features and Interfaces such as new subcommands/flags, new C++ interfaces/class member variables defined in any <resolver>/include/ file, or any change which does not otherwise effect backwards compatibility should increment minor version.
    • When users see that minor was incremented they expect to update resolver without making changes to their existing usage, but they may be able to take advantage of new features if they choose to.
    • The user should expect that existing databases may be migrated to new schemas ( or regenerated ) automatically.
    • If you added a new feature be sure to add new tests as well. If you didn't break any existing tests that should help reassure you that minor is safe to bump. If you break unit tests you may want to investigate and confirm whether these test "public" interfaces, or internals - if you didn't break any public interfaces this should help reassure you that minor is safe to bump.
  • Removed Features or Breaking Changes such as removed subcommands/flags, removed interfaces/class member variables defined in any <resolver>/include/ file, or any change which may break existing usage patterns should increment major version.
    • When users see that major version was incremented they know that they should only perform an update if they have available time migrate some existing usage of resolver in their software.
    • If you break any integration tests and need to modify their output, you almost certainly need to bump the major version. If you break unit tests of public interfaces you should bump major version.

Follow the rules above strictly, and while we ideally want to avoid bumping major versions when possible - do not concern yourself with "having a high version number".

Semantic version numbers are not used in marketing materials, and are intended to indicate certain categories of software changes to developers and automated tools ( particularly CI/CD integration test suites ). These readers could care less if resolver is at version 3.2.1 or 30000.2.1!

resolver Software Version

Updates to resolver version numbers are controlled by the text file <resolver>/version ( in the repository root ). This file is used to populate the CPP variable FLOX_RESOLVER_VERSION, the nix derivation's version number, and the pkg-config manifest file's version.

Publishing releases on GitHub using their WebUI is recommended AFTER you've followed the process for creating/updating release tags described below.

Creating Release Tags

Tagging release commits as v<MAJOR>.<MINOR>.<PATCH> is required, including aliases for latest, v<MAJOR>, and v<MAJOR>.<MINOR>. These tags are used by consuming repositories to detect breaking changes in public interfaces and minimum usable v<MAJOR>.<MINOR> version ( to have access to certain features ). This allows automated update/upgrade utilities to be used at scale.

For example lets say that we are releasing a new minor version which moves us from v4.1.3 to v4.2.0, we would perform the following:

# Make sure we're up to date, and on `main'.
$ git fetch;
$ git checkout main;

$ OLD_VERSION="$( < ./version; )";
# Modify old version, you can do this manually or using `semver'
# ( available in the `nix develop' shell ).
$ nix develop -c semver -i minor "$OLD_VERSION" > version;

$ NEW_VERSION="$( < ./version; )";
$ echo "$NEW_VERSION";
4.2.0

# Make a release commit
$ git add ./version;
$ git commit -m "release v$NEW_VERSION";

# Tag `HEAD' with the full `v<MAJOR>.<MINOR>.<PATCH>'
$ git tag -a "v$NEW_VERSION" -m "release v$NEW_VERSION";

# Push the release commit
$ git push;

# Update alias tags

# Point `v<MAJOR>.<MINOR>' to new release.
$ git tag -f "v${NEW_VERSION%.*}" "v$NEW_VERSION";

# Point `v<MAJOR>' to `v<MAJOR>.<MINOR>'.
$ git tag -f "v${NEW_VERSION%%.*}" "v${NEW_VERSION%.*}";

# Point `latest' to `v<MAJOR>'.
$ git tag -f 'latest' "v${NEW_VERSION%%.*}";

# Push the tags!
$ git push origin --tags --force;

Congratulations - you basically cut a release! Next you might cruise over to github.com to the repository page and make a new release ( under the "Releases" section in the right hand panel ). When making a release just be sure to select the v<MAJOR>.<MINOR>.<PATCH> tag as the "release tag", and you're ready to roll!