Tags denote releases.
Any commit merged to main
is expected to be release ready,
with the exception of the version
in Cargo.toml
.
For more detail, see the release process.
Broker follows semver:
- MAJOR version indicates a user facing breaking change.
- MINOR version indicates backwards compatible functionality improvement.
- PATCH version indicates backwards compatible bug fixes.
The initial beta releases of Broker use 0
as the major version; when this changes to 1
it will not necessarily indicate a breaking change, but future major version increases will.
Broker:
- Tracks the latest version of the Rust compiler and associated tooling at all times.
- Tracks the latest Rust language edition.
- Aggressively upgrades dependencies. We rely on testing to validate our dependencies work.
We recommend Visual Studio Code with the rust-analyzer
extension.
Install Rust here: https://www.rust-lang.org/tools/install
Note: the goal is that most common tasks are in Makefile
, see that for pointers!
For any contributors, we recommend the following tools, although they're not required:
cargo edit # https://lib.rs/crates/cargo-edit
cargo nextest # https://nexte.st/
cargo upgrade # https://lib.rs/crates/cargo-upgrades
cargo sqlx # https://lib.rs/crates/sqlx-cli
If you're a FOSSA employee who'll be performing releases, we use cargo-dist
and cargo-release
:
cargo dist # https://github.com/axodotdev/cargo-dist
cargo release # https://github.com/crate-ci/cargo-release
Our release process is generated with cargo dist
.
To regenerate it, run:
cargo dist generate-ci github \
--installer github-powershell \
--installer github-shell
We use musl
with jemalloc
for static builds.
For more information, including why we use these particular options, see the static binary reference.
Sometimes, especially when debugging a platform build issue, it's useful to "cross compile" the project from your home operating system to a destination operating system.
Steps to do so are located in the cross compilation reference.
Broker uses insta to perform snapshot testing of outputs.
Refer to insta
's getting started guide for optimal usage.
The short version of the workflow is that if you get "snapshot errors" during tests, run `cargo insta test --review" to review the changes and accept/deny them as intentional.
We store migrations in db/migrations
(this is different than sqlx
's default of just migrations
).
To create a migration, ensure sqlx-cli
is installed above and run:
# use underscores for any spaces in <name>
; cargo sqlx migrate add --source db/migrations -r <name>
Then fill out the newly generated up
and down
scripts.
Up migrations are automatically applied when Broker boots up, but they can be automatically applied:
; cargo sqlx migrate run --source db/migrations
; cargo sqlx migrate revert --source db/migrations
Applying up migrations always migrates all the way to current, while reverting does one step at a time:
; cargo sqlx migrate run --source db/migrations
Applied 20230313231558/migrate state 1 (202.166µs)
Applied 20230313231721/migrate state 2 (135.833µs)
Applied 20230313231723/migrate state 3 (124.667µs)
; cargo sqlx migrate revert --source db/migrations
Applied 20230313231723/revert state 3 (851.083µs)
; cargo sqlx migrate revert --source db/migrations
Applied 20230313231721/revert state 2 (593.584µs)
; cargo sqlx migrate revert --source db/migrations
Applied 20230313231558/revert state (661.875µs)
; cargo sqlx migrate revert --source db/migrations
No migrations available to revert
To see migration state, run:
; cargo sqlx migrate info --source db/migrations
20230313231558/pending state
Make your code look like the code around it. Consistency is the name of the game.
You should submit changes to this doc if you think you can improve it, or if a case should be covered by this doc, but currently is not.
Use rustfmt
for formatting.
Our CI setup enforces that all changes pass a rustfmt
run with no differences.
Our CI systems ensure that all patches pass clippy
checks.
Comments should describe the "why", type signatures should describe the "what", and the code should describe the "how".
We use the Rust API Guidelines during code review; if you want to get ahead of the curve check it out!
Ideally, every PR should check for updated dependencies and update them if applicable; if this is not realistic at minimum every non-bugfix release must ensure dependencies are up to date.
While in a pre-release state, the version
field in Cargo.toml
displays at least the
minimal next version with a pre-release indicator.
For example, if version 0.1.0
was just released, the next merge into main
must set version
to
at least 0.1.1-pre
. If the next release is known to be a specific version, that's okay to use as well:
for example if we know 0.2.0
is the next planned release, we can set it to 0.2.0-pre
.
When the final commit for that version is merged, it must ensure version
is accurate.
Reusing the previous example, after a slew of PRs, the final one would set version
to 0.2.0
.
After this commit is merged to main
, push a tag (recommended: using cargo release tag
)
matching the version
field, with a v
prefix.
In the future, the plan is to automate the release process with make release
.
It is recommended to instead use cargo release
(cargo install cargo-release
for installation), which automates much of this process and has
some safety checks (for example it ensures you're tagging on main
):
cargo release tag # Review the planned actions
cargo release tag -x # Execute the planned actions
If instead you wish to do this manually, this is an example of what to do:
git checkout main # Ensure you're on main
git pull # Ensure you're tagging the latest commit
git tag v0.2.0 # Validate this is correct, and don't forget the `v`
git push --tags # Push the new tag to the remote.
Broker provides configurable branch/tag scanning for every integration. You can customize your scans through these fields listed in the integrations section of your config.yml:
integrations:
- type: git
import_branches: true # Defaults to true
watched_branches: # If unspecified, Broker will try to set to main or master if present
- main
- release*
import_tags: false # Defaults to false
If these fields are not set, import_branches
will be set to true
, import_tags
will be set to false
, and Broker
will make a best effort approach to set watched_branches
to main
or master
if it is present in the remote.
In order to scan specific branches, import_branches
must be set to true
and the list of branches you intend to scan should be provided under watched_branches
. Having watched_branches
set while having import_branches
set to false
is an invalid
combination and will cause Broker to throw errors.
Glob matching is also provided with your branches. If one of your watched_branches is release*
and your remote contains branches release1
, release2
, and release-3
. Then all three
of those branches will be scanned due to glob matching.
In order to allow Broker to scan tags in your remote, import_tags
must be set to true
Toggling import_branches
from true
to false
will remove all existing uploaded scans for ALL branches of that particular remote in your local database (this does NOT delete your scans in the FOSSA UI). If toggled from false
to true
, Broker will perform as if it is scanning the listed watched_branches
for the first time. On subsequent poll cycles, Broker will import the latest changes from your configured branches since the last revision (skipping any intermediate commits).
Toggling import_tags
from true
to false
will remove all existing uploaded scans for ALL tags of that particular remote in your local database (this does NOT delete your scans in the FOSSA UI). If toggled from false
to true
, Broker will perform as if it is scanning all the remote's tags for the first time. This would mean that all tags for that remote would be scanned. On subsequent poll cycles, Broker will import all created or changed tags since the last poll cycle.