8000 docs: format CONTRIBUTING.md by matifali · Pull Request #8973 · coder/coder · GitHub
[go: up one dir, main page]
Skip to content

docs: format CONTRIBUTING.md #8973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 8, 2023
Merged

docs: format CONTRIBUTING.md #8973

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 26 additions & 26 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@

We recommend using the [Nix](https://nix.dev/) package manager as it makes any pain related to maintaining dependency versions [just disappear](https://twitter.com/mitchellh/status/1491102567296040961). Once nix [has been installed](https://nixos.org/download.html) the development environment can be _manually instantiated_ through the `nix-shell` command:

```
$ cd ~/code/coder
```shell
cd ~/code/coder

# https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
$ nix-shell
nix-shell

...
copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https://cache.nixos.org'...
Expand All @@ -19,18 +19,17 @@ copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from

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!

```
$ cd ~/code/coder
$ echo "use nix" >.envrc
$ direnv allow
```shell
cd ~/code/coder
echo "use nix" >.envrc
direnv allow
```

Now, whenever you enter the project folder, `direnv` will prepare the environment for you:
Now, whenever you enter the project folder, [`direnv`](https://direnv.net/docs/hook.html) will prepare the environment for you:

```
$ cd ~/code/coder
```shell
cd ~/code/coder

# https://direnv.net/docs/hook.html
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
Expand All @@ -53,15 +52,15 @@ Alternatively if you do not want to use nix then you'll need to install the need
- [`pg_dump`](https://stackoverflow.com/a/49689589)
- on macOS, run `brew install libpq zstd`
- on Linux, install [`zstd`](https://github.com/horta/zstd.install)
- [`pkg-config`]()
- `pkg-config`
- on macOS, run `brew install pkg-config`
- [`pixman`]()
- `pixman`
- on macOS, run `brew install pixman`
- [`cairo`]()
- `cairo`
- on macOS, run `brew install cairo`
- [`pango`]()
- `pango`
- on macOS, run `brew install pango`
- [`pandoc`]()
- `pandoc`
- on macOS, run `brew install pandocomatic`

### Development workflow
Expand Down Expand Up @@ -108,13 +107,14 @@ Database migrations are managed with [`migrate`](https://github.com/golang-migra

To add new migrations, use the following command:

```
$ ./coderd/database/migrations/create_fixture.sh my name
```shell
./coderd/database/migrations/create_fixture.sh my name
/home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
/home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
Run "make gen" to generate models.
```

Run "make gen" to generate models.

Then write queries into the generated `.up.sql` and `.down.sql` files and commit
them into the repository. The down script should make a best-effort to retain as
much data as possible.
Expand All @@ -140,8 +140,8 @@ migration of multiple features or complex configurations.

To add a new partial fixture, run the following command:

```
$ ./coderd/database/migrations/create_fixture.sh my fixture
```shell
./coderd/database/migrations/create_fixture.sh my fixture
/home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
```

Expand All @@ -153,9 +153,9 @@ To create a full dump, run a fully fledged Coder deployment and use it to
generate data in the database. Then shut down the deployment and take a snapshot
of the database.

```
$ mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
$ pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
```shell
mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
```

Make sure sensitive data in the dump is desensitized, for instance names,
Expand All @@ -164,8 +164,8 @@ emails, OAuth tokens and other secrets. Then commit the dump to the project.
To find out what the latest migration for a version of Coder is, use the
following command:

```
$ git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
```shell
git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
```

This helps in naming the dump (e.g. `000069` above).
Expand Down
0