* Rationale
:PROPERTIES:
:CUSTOM_ID: rationale
:END:

** OrgMode
:PROPERTIES:
:CUSTOM_ID: orgmode
:END:
#+begin_quote
[[https://orgmode.org][OrgMode]] is one of the best tools for keeping on track with what needs to be done
and when. And, contrary to myth, it doesn't need [[https://www.youtube.com/watch?v=cxoE2FhOIgI][Emacs]], just a text editor. Org
can be used with a variety of other tools and editors once you understand the
basics.

Org, at its very heart, is a structured text file. It has headers, subheaders,
and keywords that allow other tools to parse files into agendas and to-do lists.

-- https://opensource.com/article/19/1/productivity-tool-org-mode
#+end_quote

Contrary to myth, you don't need [[https://www.youtube.com/watch?v=cxoE2FhOIgI][Emacs]] to adopt [[https://orgmode.org][OrgMode]] - unless you want to.
Most flat-text editor have plugins that help create and manage Org files:

- https://vscode-org-mode.github.io/vscode-org-mode/
- https://github.com/jceb/vim-orgmode
- https://github.com/nvim-orgmode/orgmode
- https://github.com/nvim-neorg/neorg

** Conventional Commits
:PROPERTIES:
:CUSTOM_ID: conventional-commits
:END:
This project adheres to [[https://www.conventionalcommits.org/en/v1.0.0/][Conventional Commits]], [[https://semver.org/spec/v2.0.0.html][Semantic Versioning]], and [[https://keepachangelog.com/en/1.0.0/][Keep a
Changelog]]. They can profoundly intertwine and, when so, they must seamlessly
work in concert to fully appreciate their benefits. With Conventional Commits
central to automation arising from combining these best practices, guaranteeing
that all commits adhere to it becomes paramount. Manually enforcing best
practices and guaranteeing contracts in a code base befalls under the inadequate
and cumbersome category. Thus, this project relies on both [[#local-tooling][local tooling]]
together with CI pipelines, to make sure - as best as they can - that changes
pushed to this repository don't break contract.

** Semantic Versioning
:PROPERTIES:
:CUSTOM_ID: semantic-versioning
:END:
As defined by [[https://semver.org/][Semantic Versioning 2.0]]:

- Patch (1._.x) releases /should solely/ contain bug fixes or documentation
  changes. Besides, these releases shouldn't change runtime behavior.

- Minor (1.x) releases may contain new functionality, minor dependency updates,
  deprecations, and larger internal implementation changes.

#+begin_quote
[!IMPORTANT]
This project automates versioning and adopts [[#fully-automated-releases][fully automated
releases]] with [[https://release-plz.ieni.dev][=release-plz=]].
#+end_quote

** Commits and Pull Requests
:PROPERTIES:
:CUSTOM_ID: commits-and-pull-requests
:END:
For all information about commits and pull requests, please refer to the
[[file:/docs/CONTRIBUTING.org#pull-requests][Contributing]] guidelines.

** Intentional Code
:PROPERTIES:
:CUSTOM_ID: intentional-code
:END:
Always strive to write [[https://www.youtube.com/watch?v=8j4fhsLcT4k][intentional Code]]. =Intentional Code= is much more than
avoiding obscure and incomprehensible variables and functions names; however,
these are a good start give meaning to code.

** Documentation
:PROPERTIES:
:CUSTOM_ID: documentation
:END:
Always write [[https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html][documentation comments]] and spellcheck them to avoid typos and
mistakes.

** Application Security
:PROPERTIES:
:CUSTOM_ID: application-security
:END:
This project strives, in [[https://www.schneier.com/essays/archives/2000/04/the_process_of_secur.html][a constantly evolving process]], to apply [[https://www.ibm.com/topics/application-security][=AppSec=]] [[https://www.youtube.com/watch?v=hDvz8KivY_U][during
the entire development life cycle]], as best as it can.

*** Minimum Supported Rust Version
:PROPERTIES:
:CUSTOM_ID: minimum-supported-rust-version
:END:
The project strives to stay up to date and on par with Rust releases, to avoid
legacy and stagnation, as =AppSec= best practices dictate.

** Local Tooling
:PROPERTIES:
:CUSTOM_ID: local-tooling
:END:
Besides standardized [[https://www.rust-lang.org/tools][tooling]] and [[https://doc.rust-lang.org/beta/style-guide/index.html][conventions]], default =rustfmt= and =clippy=,
this project relies on [[https://rustsec.org][RustSec]] to inspect supply chain, and [[https://trufflesecurity.com][=trufflehog=]] to
avoid sharing secrets in the code base. Likewise, this project relies on
[[https://github.com/DavidAnson/markdownlint-cli2][=markdownlint-cli2=]] and [[https://github.com/pre-commit/pre-commit-hooks][=pre-commit-hooks=]]. All conveniently enforced with [[https://githooks.com][Git
Hooks]].

** Fully Automated Releases
:PROPERTIES:
:CUSTOM_ID: fully-automated-releases
:END:
Appropriately implementing Conventional Commits enables [[https://blog.orhun.dev/automated-rust-releases/][fully automated
releases]]. For this purpose, this project relies on [[https://release-plz.ieni.dev][release-plz]]. To [[https://release-plz.ieni.dev/docs/changelog/format][automate
changelog]]. To handle dependency updates, [[https://release-plz.ieni.dev/docs/semver-check][semantic version management]], and
[[https://crates.io][crates.io]] releases. Upon successful pipelines, =release-plz= invokes [[https://opensource.axo.dev/cargo-dist/][cargo-dist]]
to create GitHub releases and packaging for various platforms, along with binary
artifacts and installers.