eza/CONTRIBUTING.md

Contributing to eza

If you'd like to contribute to eza, there are several things you should make sure to familiarize yourself with first.

• Code of conduct Contributor Covenant Code of Conduct
• Requirement of conformance to Conventional Commits
• Requirement of conformance to Semantic Versioning
• The Security Policy
• Free and Open Source (FOSS) software

Hacking on eza

It is strongly recommended that you install Nix for hacking on eza. We leverage nix as a way to easily test and distribute eza to many users, and it allows us to provide multiple tools easily for developers. Instead of having to install each dependency manually and setting up a development environment, Nix allows you to use the same environment as the devs use.

Therefore, it is useful that you have a version of Nix installed with the "experimental" feature flakes enabled. Further, to make hacking on eza as easy as possible for yourself, you'd do yourself a favor to install direnv.

When you enter the eza repository, if you have direnv installed, you'll be prompted to allow it with direnv allow. Doing this will save you from having to manually enter the development environment each time you open the folder. If you don't have direnv installed however, you can run nix develop in a pinch, to enter the direnv.

The development environment includes basic checks of conformance to conventional commits, cargo clippy lints, and much more.

It also contains a pre-commit-hook making it a lot easier not to make potential mistakes that will unnecessarily delay getting your PRs accepted. Most importantly, it ensures your commits are conforming to conventional commits.

Some useful commands include:

• nix flake check: checks everything is correct.
• nix build: build eza.
• nix build .#test: runs eza's cargo tests
• nix build .#clippy: runs clippy on eza
• nix fmt: automatically formats your code as required by flake cheks and pre-commit-hooks.nix
• just itest: runs integration tests

The just command runner can be used to run some helpful development commands, in a manner similar to make. Run just --list to get an overview of what’s available.

To compile the manual pages, you will need pandoc, which the nix flake should have installed for you. The just man command will compile the Markdown into manual pages, which it will place in the target/man directory.

eza depends on libgit2 for certain features. If you’re unable to compile libgit2, you can opt out of Git support by running cargo build --no-default-features. Again, the nix flake should have taken care of this for you, if not, please file an issue.

If you intend to compile for musl, you will need to use the flag vendored-openssl if you want to get the Git feature working. The full command is cargo build --release --target=x86_64-unknown-linux-musl --features vendored-openssl,git.

Creating a PR

First, use the pull request template.

Please make sure that the thing you worked on... actually works. Make sure to also add how you ensured this in the PR description. Further, it's expected that you do your best to check for regressions.

If your PR introduces a flag, you MUST:

• Add completions for bash, zsh, fish, nushell
• Add documentation to the man page
• Add your option to the help flag
• Add your option to the README.md

Before submitting, you SHOULD have run nix flake check and ensured that all issues are addressed. For formatting issues, nix fmt will format the code for you. Most clippy issues can be resolved with cargo clippy --fix (although it might be educational to fix them yourself). If you have reuse issues, you can run the following command to annotate your code:

Here are the absolute basics:

• your commit summary MUST follow conventional commits.
• your commits SHOULD be separated into small, logical chunks.
• reviewers may ask you to rebase your commits into more sensible chunks.
• your PR will need to pass CI and local cargo test.
• you may be asked to refactor parts of your code by reviewers.

Remember that no one here is an employee, and treat everyone with respect, as the code of conduct specifies. Also remember to be patient if it takes a while to get a response on your PR. Usually it doesn't, but there's only so many hours in a day, and if possible, there would be no delay. The delay alone is evidence of it's own necessity.

Commit Messages

A common commit message contains at least a summary and reference with closing action to the corresponding issue if any, and may also include a description and signature.

Summary

For you commit messages, please use the first line for a brief summary what the commit changes. Try to stay within the 72 char limit and prepend what type of change. See the following list for some guidance:

• feat: adds a new feature to eza
• feat(zsh): adds something to zsh completion
• refactor: revises parts of the code
• docs(readme): revise the README
• docs(man): revision of the man pages
• fix: bugfix in the code base
• fix(ci): bugfix in the continuous integration
• ...

Note that this list is not complete and there may be cases where a commit could be characterized by different types, so just try to make your best guess. This spares the maintainers a lot of work when merging your PR.

Description

If you commit warrants it due to complexity or external information required to follow it, you should add a more detailed description of the changes, reasoning and also link external documentation if necessary. This description should go two lines below the summary and except for links stay in the 80 char limit.

Issue Reference

If the commit resolves an issue add: Resolves: #abc where abc is the issue number. In case of a bugfix you can also use Fixes: #abc.

Signature

You may add a signature at the end two lines below the description or issue reference.

Example

Here is an example of a commit message for a breaking change that follows these rules:

fix(hyperlinks)!: TextCell building of detailed grid view, hyperlink, icon options

The hyperlink option adds an escape sequence which in the normal TextCell
creation also becomes part of the length calculation. This patch applies
the same logic the normal grid already did, by using the filenames bare
width when a hyperlink is embedded. It also respects the ShowIcons
option just like the normal grid view.

BREAKING CHANGE: The style codes for huge file and units where
documented to be `nt` and `ut` but the code was using `nh` and `uh`.
The code has been updated to match the documented style codes.
EXA_COLORS using style codes `nh` and `uh` will need to be updated to
use `nt` and `ut`.

Resolves: #129
Ref: #473, #319

Co-authored-by: 9glenda <plan9git@proton.me>
Signed-off-by: Christina Sørensen <christina@cafkafk.com>

Additional Examples

• feat: add column selection
• fix(output): fix width issue with columns
• test(fs): add tests for filesystem metadata
• feat!: breaking change / feat(config)!: implement config file
• chore(deps): update dependencies

Commit types

• build: Changes that affect the build system or external dependencies (example libgit2)
• ci: Changes to CI configuration files and scripts (example scopes: Nix, Vagrant, Docker)
• chore: Changes which do not change source code or tests (example: changes to the build process, auxiliary tools, libraries)
• docs: Documentation, README, completions, manpage only
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves or addresses a performance issue
• refactor: A code change that neither fixes a bug nor adds a feature
• revert: Revert something
• style: Changes that do not affect the meaning of the code (example: clippy)
• test: Adding missing tests or correcting existing tests