Functionality:
User faced functionality is available through `just upgrade-rust`
recipe. It updates Rust versions in the following files through out the
project:
- .gitlab-ci.yml
- Cargo.toml
- clippy.toml
- rust-toolchain.toml
- Checks whether there are any changes of the working copy or in git
index and refuse to proceed if any asking to commit or stash them.
- Checks current git branch if it does not contains mentions of current stable
Rust version (with underscores instead of dots) it interactively propose to
create a new branch.
- Pulls current stable Rust version from
https://static.rust-lang.org/dist/channel-rust-stable.toml to upgrade
to it if not specific version was given, i.e. `just upgrade-rust 1.90`
upgrades version to 1.90 no metter what the current stable Rust
version is at the moment.
- Upgrades each of the place with where Rust version is used to pulled
current stable Rust version outputing details about upgrade:
- .gitlab-ci.yml
- Cargo.toml
- clippy.toml
- rust-toolchain.toml
- Interactively asks whether to commit the changes and if agreed commits them
to git with detailed message of what was upgraded and to which version.
- Reminds about the need to fix possible compilation and linting errors and
warnings after upgrade.
Implementation:
Functionality is delivered through main public "upgrade-rust" just
recipe and set of private (starts with underscore) recipes. Private
recipes still can be called from command line
(i.e. for debugging purposes) but they are not listed in the list of
tasks when you type `just` or `just --list`.
For example, you can still call `just _rust-stable-version` to see what
is current stable version of Rust which is retrieved by script.
"upgrade-rust" has dependency (or pre-dependency)
"_ensure-no-vcs-changes" recipe to check for absence of code changes and
post-dependency "_upgrade-rust-fixes-reminder" for the reminder of
compilation and linting fixes.
The main body of "upgrade-rust" recipe extract current versions of Rust
from number of files (called OLD in the code) to be able to output
upgrade messages of what was upgraded.
For this it uses the following private recipes:
- _current-ci-rust-version
- _current-cargo-rust-version
- _current-clippy-rust-version
- _current-toolchain-rust-version
Each of that recipes (with help of variables) encodes specifics of what, how
and from which file should be retrieved.
"_upgrade-rust-git-create-branch" makes check for the current git branch
and interactively propose to create new one switching to it.
The main workflow of version upgrade in different files is in
"_upgrade-rust" private recipe
(yep, there is upgrade-rust user faced recipe and _upgrade-rust a private one).
"_upgrade-rust" is supplied with specific values to upgrade Rust version
e.g. in .gitlab-ci.yml or in rust-toolchain.toml.
So, "upgrade-rust" calls the following tasks
- _upgrade-rust-ci
- _upgrade-rust-cargo
- _upgrade-rust-clippy
- _upgrade-rust-toolchain
to do the upgrade which supply details to "_upgrade-rust" and call it.
After changes of version "upgrade-rust" calls "_upgrade-rust-git-commit"
recipe to commit changes supplying all the details about upgrade, e.g.
old versions, new version and list of files where Rust version was
changed. "_upgrade-rust-git-commit" asks whether you want to commit
changes, if you agree it makes up a commit message and produce commit.
Functionality of editing quite heavily rely on "sed" utility with some
help from tq (tomlq).
For VCS related operations like branch creation, commiting "git" CLI is
used.
Extension:
The implementation design makes it fairly easy to extend recipes to
support new places where Rust has to be upgraded or remove such support
if some files was removed from source tree.
To add support for new place to perform upgrade:
- Add bunch of variables to justfile, e.g.
CARGO_FILE_NAME := 'Cargo.toml'
CARGO_FILE_PATH := absolute_path(CARGO_FILE_NAME)
CARGO_RUST_VERSION_QUERY := 'package.rust-version'
Addition of CARGO_RUST_VERSION_QUERY depends on format of your file
and how you will implement your "_current-cargo-rust-version".
Obviously replace CARGO/cargo in names of variables and recipes with
your place name.
- Add "_current-cargo-rust-version" recipe to retrieve currently used
Rust version from your location, rename the function according to the
new place.
- Add place specific upgrade recipe named properly, .e.g "_upgrade-rust-cargo"
which calls to "_upgrade-rust" and supply all the required arguments like
file path, file name, target version, sed command to change the
version and some parts of the messages to make proper reporting about
upgrade process.
- Add newly added recipes to the for-loops in "upgrade-rust" recipe, so
they can be called.
- Add newly added FILE_PATH and FILE_NAME variables to the call of
"_upgrade-rust-git-commit" in "upgrade-rust" recipe, so new place can
be listed in git commit and the changes in it can be added to the
commit.
Changes:
- Extend list of dependencies in README.md with command line tools
required for "upgrade-rust" recipe:
- curl
- sed
- tq (from `tomlq` crate)
- git
- Refer to "upgrade-rust" recipe in newly added "Contribution/Housekeeping"
sesion of README.md.
- Add bunch of variables to justfile related to number of private
recipes to compound functionality of "upgrade-rust":
- SED_RUST_VERSION_REGEX
- RUST_MANIFEST_STABLE_TOML_URL
- RUST_MANIFEST_STABLE_VERSION_QUERY
- RUST_MANIFEST_STABLE_VERSION_PARSE_REGEX
- DEFAULT_RUST_STABLE_VERSION_FORMAT
- GITLAB_CI_FILE_NAME
- GITLAB_CI_FILE_PATH
- CARGO_FILE_NAME
- CARGO_FILE_PATH
- CARGO_RUST_VERSION_QUERY
- CLIPPY_FILE_NAME
- CLIPPY_FILE_PATH
- CLIPPY_RUST_VERSION_QUERY
- TOOLCHAIN_FILE_NAME
- TOOLCHAIN_FILE_PATH
- TOOLCHAIN_RUST_VERSION_QUERY
- GIT_BRANCH_NAME_PREFIX
- Add "upgrade-rust" recipe which upgrade Rust version in the following
files:
- .gitlab-ci.yml
- Cargo.toml
- clippy.toml
- rust-toolchain.toml
- Add private just recipes to delivery different aspects of compound
functionality of "upgrade-rust" recipe:
- _ensure-no-vcs-changes
- _upgrade-rust-git-create-branch
- _upgrade-rust-fixes-reminder
- _upgrade-rust-git-commit
- _upgrade-rust
- _upgrade-rust-ci
- _upgrade-rust-cargo
- _upgrade-rust-clippy
- _upgrade-rust-toolchain
- _rust-stable-version
- _current-ci-image
- _current-ci-rust-version
- _current-cargo-rust-version
- _current-clippy-rust-version
- _current-toolchain-rust-version
Additional changes:
- In case of necessity specific binary can be provided for "just build"
recipe, e.g. "just build -p hagrid" or "just build -p hagridctl".
Code review issue: https://gitlab.com/keys.openpgp.org/hagrid/-/merge_requests/214#note_2482960066
Changes:
- Remove "hagrid-delete" bin declaration from Cargo.toml.
- Remove "clap" dependency for "hagrid" crate in Cargo.toml as after
moving "hagrid-delete" to "hagridctl" "hagrid" crate does not use
"clap" any more.
- Remove "run-hagrid-delete" recipe with its "hagrid-delete" and
"delete" aliases from justfile.
- Update Cargo.lock.
- Create "delete" command for "hagridctl" by adding cli::Command::Delete
variant which previously were hagrid-delete::cli::Cli struct.
- Move "delete" module with command handler ("run" function) from
"hagrid" crate to hagridctl::delete.
- Extend hagridctl::cli::dispatch_cmd() function with processing of
cli::Command::Delete variant and call to hagridctl::delete::run.
- Move print_errors() from hagrid::delete::cli module to hagrdictl::cli.
- Move KeyDatabase instantiation from hagrid/src/main.rs into
hagridctl::delete::run command handler as this way of database
instantiation is specific to "delete" command.
Probably later we have to reconsider how we instantiate database for
all the commands to avoid reimplementing that functionality every time
and duplicating the code.
That move caused change in signature of hagridctl::delete::run
function. Now we pass base path instead of db reference.
This allows for much more convenient cmd binary launching without the need
to remember distinction bitween binaries in main crate (hagrid) and
others (hagridctl, tester) and need to provide additional -- to cargo to
pass arguments to binaries.
Apart from convenience it also provide kinda "documentation" of binary
artifacts in the project as "run" group in just collect all the
artifacts together.
Changes:
- Add new named aliases for `just run` which runs "hagrid" binary with web
server:
- run-hagrid
- hagrid
- Add new recipe to run "hagrid-delete" binary "run-hagrid-delete".
- Alias "run-hagrid-delete" recipe as
- hagrid-delete
- delete
- Add new recipe to run "hagridctl" crate with default binary
"run-hagridctl".
- Alias "run-hagridctl" recipe as
- hagridctl
- Add new recipe to run "tester" crate with default binary "run-tester".
- Alias "run-tester" recipe as
- tester
To install `just` follow instructions in
documentation https://just.systems/man/en/packages.html .
Full list of recipes and their description can be viewed by running
`just` command in project's root directory.
But here is the list of added commands for documentation sake:
- init # Perform initial setup of developer's system.
- init-rocket-config # Copy Rocket's template configuration from Rocket.toml.disk to Rocket.toml. Rocket is Rust web framework. See https://rocket.rs/guide/v0.5/configuration/#configuration
- just-fmt # Format justfile
- cargo-fmt # Format Rust code in all packages (aka path based dependencies)
- fmt # Format all code [alias: f]
- just-lint-fmt # Check justfile formatting
- cargo-lint-fmt # Check Rust code formatting in all packages (aka path based dependencies)
- lint-fmt # Check formatting of all code [alias: lf]
- clippy-lint # Lint Rust code with Clippy [alias: cl]
- lint # Lint all code [alias: l]
- clippy-fix *args # Apply Clippy's lint suggestions, i.e. fix Clippy linting warnings or errors
- cargo-fix *args # Fix compilation warnings by applying compiler suggestions
- fix *args # Fix lint and compilation warnings and errors. Pass given arguments to all sub-recipes, i.e. `just fix --allow-dirty` calls `just cargo-fix --allow-dirty` and `just clippy-fix --allow-dirty`.
- check # Check Rust code errors [alias: c]
- build # Compile Rust code [alias: b]
- test args='--workspace' # Run all tests (i.e. --workspace), but when args given pass them to `cargo test`, e.g. `just test fs::tests::init` [alias: t]
- run # Run web server [alias: r]
- watch-check *args # Run continuous check of Rust code errors. Detect file changes and repeat check automatically. Ctrl+c to exit. You can pass additional arguments, e.g. --notify (-N). [alias: wc]
- watch-run *args # Run web server and automatically restart on changes. Ctrl+c to exit. You can pass additional arguments, e.g. --notify (-N). [alias: wr]
- watch-test *args # Run tests every time files changed. Ctrl+c to exit. You can pass additional arguments, e.g. --notify (-N). [alias: wt]
- clean # Clean compilartion artifacts (i.e. "target" directory)
- clean-translations # Clean changes to translation files
- translate-templates # Translate *.hbs templates of web pages
- db # Open database prompt
