Contributing

Building/Testing

$ nix develop;
$ make -j;
$ ls ./bin/;
pkgdb
$ make check;
...<SNIP>...

Building Docs

Docs are generated by Doxygen.

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

Building Compilation Databases

The files .ccls and compile_commands.json are available as Makefile targets. These may be used to support various C++ language server protocols, and tools such as clang-tidy.

$ make ccls;  # an alias of `.ccls'
$ make compile_commands.json;
$ make cdb;  # a shorthand to build both

Linting

Linting is a slow process, so we recommend running it in a separate terminal while you are hacking around or go get a coffee.

Linting is performed by clang-tidy, and can be configured in the file .clang-tidy.

$ make lint;

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 pkgdb 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 /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 pkgdb 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 /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 pkgdb 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 pkgdb is at version 3.2.1 or 30000.2.1!

SQL Schema Version

Changes to the pkgdb SQL schema should be indicated by version numbers in the file /include/flox/pkgdb/read.hh using the variable sqlVersions which is used to populate newly created DBs and to detect old schemas in existing DBs.

Any changes to the schema version number should also trigger an equivalent increment to the pkgdb version number.

When changes are made to table schemas you must bump the tables version, while additions or changes to any VIEW can be reflected using the views version. Increments to the views version do not require existing databases on a user's system to become invalidated, they are simply upgraded with new VIEW definitions and their DbVersions row for pkgdb_views_schema is updated.

Increments to the tables version require all databases on a user's system to be recreated from scratch. A future extension might migrate existing data; but because the scraping operation is rather quick, we simply recreate them.

<tt>pkgdb</tt> Software Versioning

Updates to pkgdb version numbers are controlled by the text file /version ( in the repository root ). This file is used to populate the CPP variable FLOX_PKGDB_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!

Documenting Code

Doxygen Quirks

For docstrings @brief continuations have to be indented, and for whatever reason if your block is multiple lines /** has to be on its own:

 {c++}
// Renders improperly:
 
/** @brief It doesn't
  * like this.
  * I treats any unindented lines after `@brief` as _detailed documentation_.
  * So it thinks the _brief_ is "It doesn't". */
 
 
// Renders properly:
 
/**
 * @brief It does
 *        like this.
 * And this part is _correctly_ identified as _detailed documentation_.
 */