This page is for developers that want to contribute to the Versio application. It assumes that you already have basic familiarity with building Rust programs.
See ex. the book, or elsewhere on the internet for help getting started with rust.
Also, make sure you've read the project README and Installation page so that you have an idea of how Versio must be installed.
Here is the structure of "versio":
versio
├─ LICENSE.md
├─ README.md
├─ docs
│ ├─ contributing.md . . . . . . this document
│ └─ ...
├─ Cargo.toml . . . . . . . . . . project file
├─ Cargo.lock . . . . . . . . . . deps locking
├─ rustfmt.toml . . . . . . . . . format config
├─ src
│ └─ ... . . . . . . . . src and unit tests
├─ tests
│ └─ ... . . . . . . . . integration tests
└─ .github
└─ ... . . . . . . . . GitHub Actions
The versio app is very simple with minimal runtime dependencies; you
can run it locally as described in the use cases doc.
Here are the development guidelines for Versio. In order to practice them, you may need to install some tools:
$ rustup toolchain install nightly
$ rustup component add rustfmt --toolchain nightly
$ cargo install cargo-audit
$ rustup component add clippy
Unless there's a very good reason, you should never commit code that
compiles with warnings. In fact, it is suggested that you set the
RUSTFLAGS='-D warnings' before building, which treats all warnings as
errors. Most rust warnings have reasonable work-arounds; use them.
For example, "unused variable" warnings can be suppressed by starting
the variable name with an underscore (_thing). Of course, it's always
better to re-factor the code so that the variable doesn't exist, where
possible.
We generally adhere to the principles of "Clean Code", as described in the first half of Clean Code. This means well-chosen names; small, concise functions; limited, well written comments; and clear boundaries of abstraction.
We also follow best Rust and Cargo practices: using references,
iterators, functional techniques, and idiomatic use of Option,
Result, ? operator, and the type system in general. Most of this is
shown clearly in the the
book
You should keep all technical documentation--including the top-level README, code comments, and this document--up-to-date as you make changes to tests and code.
Always format your code! You should format your (compiling, tested) code before submitting a pull request, or the PR will be rejected.
We use the nightly rust
formatter, and have a
rustfmt.toml file already committed for its use. Run cargo +nightly fmt -- --check to preview changes, and cargo +nightly fmt to apply
them.
Always lint your code! You should lint your code before submitting a pull request, or the PR will be rejected.
Clippy is the standard cargo
linter. Run cargo clippy to run all lint checks.
Always audit your dependencies! If you don't, your PR will be rejected.
We use the default cargo audit
command. Run cargo audit --deny-warnings to perform a vulnerability
scan on all dependencies. The --deny-warnings flag treats warnings as
errors.
Always run tests! Obviously, if your code fails any unit or service test, then your PR will be rejected.
Any new modules created should have their own set of unit tests. Additions to modules should also expand that module's unit tests. New functionality should expand the application's integration tests.
Run cargo test to run all unit tests.
Versio uses
Yambler in
order to more easily handle repetitive GitHub Actions. The main
workflows are saved in .github/workflows-src/ and snippets in
.github/snippets/. When you create or change workflows, just run the
script yamble-repo.sh (available from
here)
which generates workflow files into ~/.github/workflows.
DON'T EDIT THE WORKFLOW FILES DIRECTLY. You should only edit the
workflow sources in workflow-src, or the snippets in snippets, and
then run the yamble-repo script. You will still need to
add/commit/push the generated files in workflow, however, in order for
GitHub Actions to use them.
As mentioned in the Yambler README, you can copy the companion script
yamble-repo-pre-push.sh to a file named .git/hooks/pre-push in your
local copy of the versio repo. This will ensure that your workflows
are synced before you share them.
When building on linux, you should set the following environment
variables before running cargo build or cargo install. The options
below are the standard locations for Ubuntu 18 (bionic).
$ export RUSTFLAGS='-D warnings -C link-args=-s'
link-args=-s passes --strip-debug to the linker, and ensures that
the resulting executable is a reasonable size: without that option, the
binary easily expand to over 100M. If you forget to include this option,
you should manually run strip on the resulting executable.
We compile using the MSVC ([M]icro[S]oft [V]isual studio [C]omponents) toolchain, which is the default. The latest version of Rust allows you to install Community Edition C Components as part of the Rust MSVC target installation; this is the easiest option if you don't already have Visual Studio installed. Otherwise, you'll need to install MSVC Visual Studio (Community Edition 2017 is tested) or its runtime components yourself.
No additional configuration is needed to build Versio for MacOS
platforms, although you may want to set RUSTFLAGS='-D warnings' to
ensure the highest-quality build.