diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 15bb998be9..4ec589f335 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,51 +2,61 @@ ## Requirements -We recommend using the [Nix](https://nix.dev/) package manager as it makes any -pain related to maintaining dependency versions -[disappear](https://nixos.org/guides/how-nix-works). Once nix -[has been installed](https://nixos.org/download.html) the development -environment can be _manually instantiated_ through the `nix-shell` command: +
-```shell -cd ~/code/coder +We recommend that you use [Nix](https://nix.dev/) package manager to +[maintain dependency versions](https://nixos.org/guides/how-nix-works). -# https://nix.dev/tutorials/declarative-and-reproducible-developer-environments -nix-shell +### Nix -... -copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https://cache.nixos.org'... -copying path '/nix/store/dxg5aijpyy36clz05wjsyk90gqcdzbam-iana-etc-20220520' from 'https://cache.nixos.org'... -copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from 'https://cache.nixos.org'... -... -``` +1. [Install Nix](https://nix.dev/install-nix#install-nix) -If [direnv](https://direnv.net/) is installed and the -[hooks are configured](https://direnv.net/docs/hook.html) then the development -environment can be _automatically instantiated_ by creating the following -`.envrc`, thus removing the need to run `nix-shell` by hand! +1. After you've installed Nix, instantiate the development with the `nix-shell` + command: -```shell -cd ~/code/coder -echo "use nix" >.envrc -direnv allow -``` + ```shell + cd ~/code/coder -Now, whenever you enter the project folder, -[`direnv`](https://direnv.net/docs/hook.html) will prepare the environment for -you: + # https://nix.dev/tutorials/declarative-and-reproducible-developer-environments + nix-shell -```shell -cd ~/code/coder + ... + copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https:// cache.nixos.org'... + copying path '/nix/store/dxg5aijpyy36clz05wjsyk90gqcdzbam-iana-etc-20220520' from 'https:// cache.nixos.org'... + copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from 'https://cache. nixos.org'... + ... + ``` -direnv: loading ~/code/coder/.envrc -direnv: using nix -direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +XDG_DATA_DIRS +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~PATH +1. Optional: If you have [direnv](https://direnv.net/) installed with + [hooks configured](https://direnv.net/docs/hook.html), you can add `use nix` + to `.envrc` to automatically instantiate the development environment: -🎉 -``` + ```shell + cd ~/code/coder + echo "use nix" >.envrc + direnv allow + ``` -Alternatively if you do not want to use nix then you'll need to install the need + Now, whenever you enter the project folder, + [`direnv`](https://direnv.net/docs/hook.html) will prepare the environment + for you: + + ```shell + cd ~/code/coder + + direnv: loading ~/code/coder/.envrc + direnv: using nix + direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +XDG_DATA_DIRS +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~PATH + + 🎉 + ``` + + - If you encounter a `creating directory` error on macOS, check the + [troubleshooting](#troubleshooting) section below. + +### Without Nix + +Alternatively if you do not want to use Nix then you'll need to install the need the following tools by hand: - Go 1.18+ @@ -73,7 +83,9 @@ the following tools by hand: - `pandoc` - on macOS, run `brew install pandocomatic` -### Development workflow +
+ +## Development workflow Use the following `make` commands and scripts in development: @@ -203,8 +215,7 @@ This helps in naming the dump (e.g. `000069` above). ### Documentation -Our style guide for authoring documentation can be found -[here](./contributing/documentation.md). +Visit our [documentation style guide](./contributing/documentation.md). ### Backend @@ -334,3 +345,17 @@ The [`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental) label can be used to move the note to the bottom of the release notes under a separate title. + +## Troubleshooting + +### Nix on macOS: `error: creating directory` + +On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause +`nix-shell` to fail to build or run `coder`. If you encounter +`error: creating directory` when you attempt to run, build, or test, add a +`mkdir` line to your `.envrc`: + +```shell +use nix +mkdir -p "$TMPDIR" +```