mirror of
https://github.com/eza-community/eza
synced 2024-09-30 05:06:30 +00:00
docs: improve CONTRIBUTING.md, README.md
Signed-off-by: Christina Sørensen <christina@cafkafk.com>
This commit is contained in:
Christina Sørensen
parent
0a7ee1d8e4
commit
2e15bad8e5
120
CONTRIBUTING.md
120
CONTRIBUTING.md
|
|
@ -1,12 +1,99 @@
|
|||
# Contributing
|
||||
# Contributing to eza
|
||||
|
||||
If you wanna contribute to `eza`, here are the absolute basics:
|
||||
- your commit summary should follow conventional commits.
|
||||
- your commits should be separated into small, logical chunks.
|
||||
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](CODE_OF_CONDUCT.md)
|
||||
- Requirement of conformance to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
||||
- Requirement of conformance to [Semantic Versioning](https://semver.org/)
|
||||
- The [Security Policy](SECURITY.md)
|
||||
- [Free and Open Source (FOSS) software](https://www.gnu.org/philosophy/free-sw.en.html)
|
||||
|
||||
## 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](https://direnv.net/).
|
||||
|
||||
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](https://github.com/casey/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](https://pandoc.org/), 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](https://github.com/rust-lang/git2-rs) 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
|
||||
|
||||
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
|
||||
|
|
@ -37,17 +124,18 @@ 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`.
|
||||
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 that follows these rules (mostly):
|
||||
Here is an example of a commit message for a breaking change that follows these rules:
|
||||
|
||||
```
|
||||
fix: TextCell building of detailed grid view for hyperlink and icon options
|
||||
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
|
||||
|
|
@ -55,7 +143,17 @@ 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.
|
||||
|
||||
Resolves #129
|
||||
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
|
||||
|
|
@ -79,7 +177,3 @@ Resolves #129
|
|||
- revert: Revert something
|
||||
- style: Changes that do not affect the meaning of the code (example: clippy)
|
||||
- test: Adding missing tests or correcting existing tests
|
||||
|
||||
### Reminders
|
||||
Put newline before extended commit body
|
||||
More details at conventionalcommits.org
|
||||
|
|
|
|||
57
README.md
57
README.md
|
|
@ -372,57 +372,12 @@ Some of the options accept parameters:
|
|||
|
||||
</details>
|
||||
|
||||
<a id="development">
|
||||
<details>
|
||||
<summary> Development </summary>
|
||||
<h1>Development
|
||||
# Hacking on eza
|
||||
|
||||
<a href="https://blog.rust-lang.org/2023/06/01/Rust-1.70.0.html">
|
||||
<img src="https://img.shields.io/badge/rustc-1.70.0+-lightgray.svg" alt="Rust 1.70.0" />
|
||||
</a>
|
||||
|
||||
</h1></a>
|
||||
|
||||
eza is written in [Rust](https://www.rust-lang.org/).
|
||||
You will need rustc version 1.56.1 or higher.
|
||||
The recommended way to install Rust for development is from the [official download page](https://www.rust-lang.org/tools/install), using rustup.
|
||||
|
||||
Once Rust is installed, you can compile eza with Cargo:
|
||||
|
||||
cargo build
|
||||
cargo test
|
||||
|
||||
- The [just](https://github.com/casey/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.
|
||||
|
||||
- If you are compiling a copy for yourself, be sure to run `cargo build --release` or `just build-release` to benefit from release-mode optimisations.
|
||||
Copy the resulting binary, which will be in the `target/release` directory, into a folder in your `$PATH`.
|
||||
`/usr/local/bin` is usually a good choice.
|
||||
|
||||
- To compile and install the manual pages, you will need [pandoc](https://pandoc.org/).
|
||||
The `just man` command will compile the Markdown into manual pages, which it will place in the `target/man` directory.
|
||||
To use them, copy them into a directory that `man` will read.
|
||||
`/usr/local/share/man` is usually a good choice.
|
||||
|
||||
- eza depends on [libgit2](https://github.com/rust-lang/git2-rs) for certain features.
|
||||
If you’re unable to compile libgit2, you can opt out of Git support by running `cargo build --no-default-features`.
|
||||
|
||||
- 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`.
|
||||
|
||||
### Developing on Nix (experimental) ❄️
|
||||
|
||||
If you have a working Nix installation with flake support, you can use nix to manage your dev environment.
|
||||
|
||||
nix develop
|
||||
|
||||
The Nix Flake has a few features:
|
||||
|
||||
- Run `nix flake check` to run `treefmt` on the repo.
|
||||
- Run `nix build` and manually test `./results/bin/eza -- <arguments>` for easy debugging.
|
||||
- Run `nix build .#test` to run `cargo test` via the flake.
|
||||
- Run `nix build .#clippy` to lint with clippy (still work in progress).
|
||||
|
||||
## Star History
|
||||
If you wanna contribute to eza, firstly, you're expected to follow our
|
||||
[code of conduct](https://github.com/eza-community/eza/blob/main/CODE_OF_CONDUCT.md).
|
||||
After having understood the code of conduct, you can have a look at our
|
||||
[CONTRIBUTING.md](https://github.com/eza-community/eza/blob/main/CONTRIBUTING.md)
|
||||
for more info about actual hacking.
|
||||
|
||||
[](https://star-history.com/#eza-community/eza&Date)
|
||||
|
|
|
|||
Loading…
Reference in a new issue