maurice/snix
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
snix/tvix/docs/src/contributing/code-&-commits.md
toastal ade0781416 docs(tvix): create Welcome + Contributing sections 
A lot of this content needs to be duplicated from the monorepo’s root
directory. However, some of the content was not relevant or could have
been more condensed in descriptions or split up for consumption that
also matched the styles of some other library documentation I had been
looking at for examples. I wanted to add the new access to Admonish
callouts but also aimed at the readablitiy in one’s text editor for the
user that needs to `cat` the docs.

In the future, a “Introduction” page would be nice to add to “Welcome”,
but I don’t think that is as clear.

Change-Id: Ibfc169c5fc3501d7eeb9a76423c6f64cd68897aa
Reviewed-on: https://cl.tvl.fyi/c/depot/+/11869
Tested-by: BuildkiteCI
Reviewed-by: flokli <flokli@flokli.de>
2024-06-27 07:16:23 +00:00

2.4 KiB
Raw Blame History

Code & Commits

Code quality

This one should go without saying — but please ensure that your code quality does not fall below the rest of the project. This is of course very subjective, but as an example if you place code that throws away errors into a block in which errors are handled properly your change will be rejected.

Usually there is a strong correlation between the visual appearance of a code
block and its quality. This is a simple way to sanity-check your work while
squinting and keeping some distance from your screen ;-)

Commit messages

The Angular Conventional Commits style is the general commit style used in the Tvix project. Commit messages should be structured like this:

    type(scope): Subject line with at most a 72 character length

    Body of the commit message with an empty line between subject and
    body. This text should explain what the change does and why it has
    been made, *especially* if it introduces a new feature.

    Relevant issues should be mentioned if they exist.

Where type can be one of:

  • feat: A new feature has been introduced
  • fix: An issue of some kind has been fixed
  • docs: Documentation or comments have been updated
  • style: Formatting changes only
  • refactor: Hopefully self-explanatory!
  • test: Added missing tests / fixed tests
  • chore: Maintenance work
  • subtree: Operations involving git subtree

And scope should refer to some kind of logical grouping inside of the project.

It does not make sense to include the full path unless it aids in disambiguating. For example, when changing the struct fields in tvix/glue/src/builtins/fetchers.rs it is enough to write refactor(tvix/glue): ….

Please take a look at the existing commit log for examples.

Commit content

Multiple changes should be divided into multiple git commits whenever possible. Common sense applies.

The fix for a single-line whitespace issue is fine to include in a different commit. Introducing a new feature and refactoring (unrelated) code in the same commit is not fine.

git commit -a is generally taboo, whereas on the command line you should be preferring git commit -p.

Tooling can really help this process. The [lazygit][] TUI or [magit][] for
Emacs are worth looking into.