|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Building/Testing |
| 4 | + |
| 5 | +``` shell |
| 6 | +$ nix develop; |
| 7 | +$ make; |
| 8 | +$ ls ./bin/; |
| 9 | +resolver |
| 10 | +$ make check; |
| 11 | +...<SNIP>... |
| 12 | +``` |
| 13 | + |
| 14 | + |
| 15 | +## Building Docs |
| 16 | + |
| 17 | +Docs are generated by [Doxygen](https://www.doxygen.nl/). |
| 18 | + |
| 19 | +```shell |
| 20 | +$ nix develop; |
| 21 | +$ make doc; |
| 22 | +$ firefox ./docs/index.html; |
| 23 | +``` |
| 24 | + |
| 25 | + |
| 26 | +## Making a Release |
| 27 | + |
| 28 | +This project follows semantic version guidelines with then |
| 29 | +scheme `<MAJOR>.<MINOR>.<PATCH>`. |
| 30 | + |
| 31 | +This means that when a release is created, the version number should be |
| 32 | +incremented using the following rules: |
| 33 | + |
| 34 | +- _Bug Fixes_ and _Optimizations_ which have no effect on the availability of |
| 35 | + public interfaces should increment _patch_ version. |
| 36 | + + When users see that _patch_ was incremented they expect to update `resolver` |
| 37 | + without making ANY changes to their existing usage. |
| 38 | + + If you didn't add any new features, and you didn't break existing tests, |
| 39 | + you should probably bump this. |
| 40 | +- _New Features_ and _Interfaces_ such as new subcommands/flags, new C++ |
| 41 | + interfaces/class member variables defined in any `<resolver>/include/` file, or |
| 42 | + any change which does not otherwise effect backwards compatibility should |
| 43 | + increment _minor_ version. |
| 44 | + + When users see that _minor_ was incremented they expect to update `resolver` |
| 45 | + without making changes to their existing usage, but they may be able to take |
| 46 | + advantage of new features if they choose to. |
| 47 | + + The user should expect that existing databases may be migrated to new |
| 48 | + schemas ( or regenerated ) automatically. |
| 49 | + + If you added a new feature be sure to add new tests as well. |
| 50 | + If you didn't break any existing tests that should help reassure you that |
| 51 | + _minor_ is safe to bump. |
| 52 | + If you break unit tests you may want to investigate and confirm whether |
| 53 | + these test "public" interfaces, or internals - if you didn't break any |
| 54 | + public interfaces this should help reassure you that _minor_ is safe |
| 55 | + to bump. |
| 56 | +- _Removed Features_ or _Breaking Changes_ such as removed subcommands/flags, |
| 57 | + removed interfaces/class member variables defined in any `<resolver>/include/` |
| 58 | + file, or any change which may break existing usage patterns should increment |
| 59 | + _major_ version. |
| 60 | + + When users see that _major_ version was incremented they know that they |
| 61 | + should only perform an update if they have available time migrate some |
| 62 | + existing usage of `resolver` in their software. |
| 63 | + + If you break any integration tests and need to modify their output, you |
| 64 | + almost certainly need to bump the _major_ version. |
| 65 | + If you break unit tests of public interfaces you should bump |
| 66 | + _major_ version. |
| 67 | + |
| 68 | +Follow the rules above strictly, and while we ideally want to avoid bumping |
| 69 | +major versions when possible - do not concern yourself with |
| 70 | +"having a high version number". |
| 71 | + |
| 72 | +Semantic version numbers are not used in marketing materials, and are intended |
| 73 | +to indicate certain categories of software changes to developers and automated |
| 74 | +tools ( particularly CI/CD integration test suites ). |
| 75 | +These readers could care less if `resolver` is at version 3.2.1 or 30000.2.1! |
| 76 | + |
| 77 | + |
| 78 | +### `resolver` Software Version |
| 79 | +Updates to `resolver` version numbers are controlled by the text file |
| 80 | +`<resolver>/version` ( in the repository root ). |
| 81 | +This file is used to populate the CPP variable `FLOX_RESOLVER_VERSION`, the |
| 82 | +`nix` derivation's version number, and the `pkg-config` manifest file's version. |
| 83 | + |
| 84 | +Publishing releases on GitHub using their WebUI is recommended AFTER you've |
| 85 | +followed the process for creating/updating release tags described below. |
| 86 | + |
| 87 | +#### Creating Release Tags |
| 88 | + |
| 89 | +Tagging release commits as `v<MAJOR>.<MINOR>.<PATCH>` is required, including |
| 90 | +aliases for `latest`, `v<MAJOR>`, and `v<MAJOR>.<MINOR>`. |
| 91 | +These tags are used by consuming repositories to detect breaking changes in |
| 92 | +public interfaces and minimum usable `v<MAJOR>.<MINOR>` version |
| 93 | +( to have access to certain features ). |
| 94 | +This allows automated `update`/`upgrade` utilities to be used at scale. |
| 95 | + |
| 96 | + |
| 97 | +For example lets say that we are releasing a new minor version which moves us |
| 98 | +from `v4.1.3` to `v4.2.0`, we would perform the following: |
| 99 | +```shell |
| 100 | +# Make sure we're up to date, and on `main'. |
| 101 | +$ git fetch; |
| 102 | +$ git checkout main; |
| 103 | + |
| 104 | +$ OLD_VERSION="$( < ./version; )"; |
| 105 | +# Modify old version, you can do this manually or using `semver' |
| 106 | +# ( available in the `nix develop' shell ). |
| 107 | +$ nix develop -c semver -i minor "$OLD_VERSION" > version; |
| 108 | + |
| 109 | +$ NEW_VERSION="$( < ./version; )"; |
| 110 | +$ echo "$NEW_VERSION"; |
| 111 | +4.2.0 |
| 112 | + |
| 113 | +# Make a release commit |
| 114 | +$ git add ./version; |
| 115 | +$ git commit -m "release v$NEW_VERSION"; |
| 116 | + |
| 117 | +# Tag `HEAD' with the full `v<MAJOR>.<MINOR>.<PATCH>' |
| 118 | +$ git tag -a "v$NEW_VERSION" -m "release v$NEW_VERSION"; |
| 119 | + |
| 120 | +# Push the release commit |
| 121 | +$ git push; |
| 122 | + |
| 123 | +# Update alias tags |
| 124 | + |
| 125 | +# Point `v<MAJOR>.<MINOR>' to new release. |
| 126 | +$ git tag -f "v${NEW_VERSION%.*}" "v$NEW_VERSION"; |
| 127 | + |
| 128 | +# Point `v<MAJOR>' to `v<MAJOR>.<MINOR>'. |
| 129 | +$ git tag -f "v${NEW_VERSION%%.*}" "v${NEW_VERSION%.*}"; |
| 130 | + |
| 131 | +# Point `latest' to `v<MAJOR>'. |
| 132 | +$ git tag -f 'latest' "v${NEW_VERSION%%.*}"; |
| 133 | + |
| 134 | +# Push the tags! |
| 135 | +$ git push origin --tags --force; |
| 136 | +``` |
| 137 | + |
| 138 | +Congratulations - you basically cut a release! |
| 139 | +Next you might cruise over to github.com to the repository page and make a new |
| 140 | +release ( under the "packages" section in the right hand panel ). |
| 141 | +When making a release just be sure to select the `v<MAJOR>.<MINOR>.<PATCH>` tag |
| 142 | +as the "release tag", and you're ready to roll! |
| 143 | + |
0 commit comments