CONTRIBUTING.md

Contributing

:wave: Hey there! Thanks for considering taking the time to contribute to git-bug. This page contains some general guidelines, and instructions for getting started as a contributor to this project.

Get the source code

Clone this repository to your system in a way you're comfortable with. Below, we show a command that clones the repository using SSH, and places it in ~/code/git-bug.

git clone git@github.com:git-bug/git-bug ~/code/git-bug

[!TIP] If you wish to clone the repository to another location on disk, change ~/code/git-bug to your desired path (e.g. your current directory can be used with . or by omitting the path argument). The rest of this documentation will refer to ~/code/git-bug in all instances, so make sure you change them there to match the location you've cloned the repository.

Software requirements

This repository uses nix to provide a consistent development environment, ensuring that each contributor has the same revision of each dependency and tool installed. It is strongly encouraged to use nix when contributing to git-bug to remove the "it works on my machine" class of errors, and ensure you have a smoother experience passing the CI pipelines (wrt formatting and such).

While you can manually install the tools and packages we use and hack on this project on your own, you will miss out on the hermeticity and standardization that our development shell provides. You may end up fighting with failing CI pipelines more often, or have to figure out how to perform various tasks on your own. Using the development shell ensures you always have every tool you need to contribute to git-bug, and that each tool is always configured correctly.

Because of this, we encourage all contributors to follow the documentation below to install the dependencies for the development shell.

[!NOTE] In the future, we will provide a container image with nix pre-installed and everything configured to get you started. This will be able to be pulled like any other image, and will be made compatible with VSCode's "devcontainer" feature and GitHub Codespaces.

For more information, see the tracking issue.

1.0 | Install nix

To install nix, you can follow the official instructions.

We recommend following the instructions for multi-user mode where applicable, instead of single-user mode.

[!IMPORTANT] The rest of this document assumes you have successfully installed nix.

2.0 | Enable nix-command and flakes

nix-command and flakes are two optional configuration properties that we depend on in order to provide the development shell. You'll need to make sure that these are enabled.

NixOS

Add the following to your system configuration:

nix.settings.experimental-features = [ "nix-command" "flakes" ];
Other

Add the following to ~/.config/nix.conf or /etc/nix/nix.conf:

experimental-features = nix-command flakes

[!IMPORTANT] The rest of this document assume you have enabled these options.

3.0 | Install and configure direnv

direnv can be used to automatically activate the development shell (using //:.envrc). It can be installed either with nix, or independently.

With nix (suggested for users new to nix) 
nix --extra-experimental-options 'flakes nix-command' profile install nixpkgs\#direnv

Next, run the following commands to apply the optional configuration for direnv. Be sure to change references to ~/code/git-bug if you have cloned the repository somewhere else.

Create a configuration file for direnv

touch ~/.config/direnv/direnv.toml

Disable the warning for shells with longer load times

This is optional, but recommended, as it helps reduce visual clutter.

nix run nixpkgs\#dasel -- -r toml -f ~/.config/direnv/direnv.toml \
  put -t int -v 0 ".global.warn_timeout"

Disable printing of the environment variables that change

This is optional, but recommended, as it helps reduce visual clutter.

nix run nixpkgs\#dasel -- -r toml -f ~/.config/direnv/direnv.toml \
  put -t bool -v true ".global.hide_env_diff"

Automatically activate the development shell

This is optional, but strongly recommended.

nix run nixpkgs\#dasel -- -r toml -f ~/.config/direnv.toml \
  put -v "~/code/git-bug/.envrc" ".whitelist.exact[]"

Alternatively, simply run direnv allow after moving into the repository for the first time.

IMPORTANT
If you choose not to allow the shell to be automatically activated, you will need to type nix develop every time you want to activate it, and this will swap you into bash and change your prompt. You'll have a far better experience allowing direnv to automatically manage activation and deactivation.

Configure your shell

This final step is crucial -- be sure to configure your shell for direnv.

Using home-manager 
programs.direnv = {
  enable = true;
  nix-direnv.enable = true;

  # one of the following, depending on your shell
  # enableZshIntegration = true;
  # enableBashIntegration = true;
  # enableFishIntegration = true;
  # enableNushellIntegration = true;

  config = {
    hide_env_diff = true;
    warn_timeout = 0;

    whitelist.exact = [ "~/code/git-bug/.envrc" ];
  };
}

4.0 | Post-installation tasks

Congratulations! If you've reached this section of the documentation, chances are that you have a working development environment for contributing to this repository. Read below for some additional tasks you should complete.

4.1 | Open a new shell

In order for the installation to take effect, you will need to open a new shell. It is recommended to do this and complete the test (described below) prior to closing the shell you ran the installation script in, just in case you run into issues and need to refer to any output it provided.

Useful development commands

  • make build - build git-bug and output the binary at ./git-bug
    • make build/debug - build a debugger-friendly binary
  • make install - build git-bug, and install it to $GOPATH/bin
  • nix fmt - format everything (configured in //:treefmt.nix)
    • nix fmt <path...> to restrict the scope to given directories or files
    • see nix fmt --help for more information
  • nix flake check to run lint/format checks and all tests defined in //nix/checks
  • go generate - generate cli documentation and shell completion files
    • this is automatically executed by many make targets, e.g. make build
  • go test ./commands -update - update golden files used in tests
    • this is required when changing the output of CLI commands, if the files in //commands/testdata/... do not match the new output format
  • pinact to pin any newly-added github action libraries
    • pinact upgrade to upgrade action libraries

[!NOTE] There is an ongoing effort to simplify the commands you need to call in our environment, with a trend toward nix, while make may continue to be supported for common workflows (e.g. building a release binary).

Submitting changes

You can submit your changes in the typical fork-based workflow to this repository on GitHub. That is: fork this repository, push to a branch to your repository, and create a pull request.

If you are in the development shell, you have the gh command line tool available for use with github.

See more