diff options
author | Igor Drozdov <idrozdov@gitlab.com> | 2022-02-15 12:36:52 +0300 |
---|---|---|
committer | Igor Drozdov <idrozdov@gitlab.com> | 2022-02-16 11:42:43 +0300 |
commit | 7bec1298c33b581ce78006bbbfa3c416f86c15c3 (patch) | |
tree | b041f61e25901440fd25351cb1dc88f81ef5a0e9 | |
parent | 40295a071463e2361f63557eab875fe870d544d2 (diff) | |
download | gitlab-shell-7bec1298c33b581ce78006bbbfa3c416f86c15c3.tar.gz |
Move code guidelines to doc/beginners_guide.md
It helps to have less verbose README.md
-rw-r--r-- | README.md | 78 | ||||
-rw-r--r-- | doc/beginners_guide.md | 76 |
2 files changed, 78 insertions, 76 deletions
@@ -42,81 +42,6 @@ Download and install the current version of Go from https://golang.org/dl/ We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy) of supporting the current stable version and the previous two major versions. -## Check - -Checks if GitLab API access and redis via internal API can be reached: - - make check - -## Compile - -Builds the `gitlab-shell` binaries, placing them into `bin/`. - - make compile - -## Install - -Builds the `gitlab-shell` binaries and installs them onto the filesystem. The -default location is `/usr/local`, but can be controlled by use of the `PREFIX` -and `DESTDIR` environment variables. - - make install - -## Setup - -This command is intended for use when installing GitLab from source on a single -machine. In addition to compiling the gitlab-shell binaries, it ensures that -various paths on the filesystem exist with the correct permissions. Do not run -it unless instructed to by your installation method documentation. - - make setup - - -## Testing - -Run tests: - - bundle install - make test - -Run gofmt: - - make verify - -Run both test and verify (the default Makefile target): - - bundle install - make validate - -### Gitaly - -Some tests need a Gitaly server. The -[`docker-compose.yml`](./docker-compose.yml) file will run Gitaly on -port 8075. To tell the tests where Gitaly is, set -`GITALY_CONNECTION_INFO`: - - export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}' - make test - -If no `GITALY_CONNECTION_INFO` is set, the test suite will still run, but any -tests requiring Gitaly will be skipped. They will always run in the CI -environment. - -## Logging Guidelines - -In general, it should be possible to determine the structure, but not content, -of a gitlab-shell or gitlab-sshd session just from inspecting the logs. Some -guidelines: - -- We use [`gitlab.com/gitlab-org/labkit/log`](https://pkg.go.dev/gitlab.com/gitlab-org/labkit/log) - for logging functionality -- **Always** include a correlation ID -- Log messages should be invariant and unique. Include accessory information in - fields, using `log.WithField`, `log.WithFields`, or `log.WithError`. -- Log success cases as well as error cases -- Logging too much is better than not logging enough. If a message seems too - verbose, consider reducing the log level before removing the message. - ## Rate Limiting GitLab Shell performs rate-limiting by user account and project for git operations. GitLab Shell accepts git operation requests and then makes a call to the Rails rate-limiter (backed by Redis). If the `user + project` exceeds the rate limit then GitLab Shell will then drop further connection requests for that `user + project`. @@ -133,7 +58,8 @@ See [PROCESS.md](./PROCESS.md) ## Contributing -See [CONTRIBUTING.md](./CONTRIBUTING.md). +- See [CONTRIBUTING.md](./CONTRIBUTING.md). +- See the [beginner's guide](doc/beginners_guide.md). ## License diff --git a/doc/beginners_guide.md b/doc/beginners_guide.md new file mode 100644 index 0000000..fecbf31 --- /dev/null +++ b/doc/beginners_guide.md @@ -0,0 +1,76 @@ +## Beginner's guide to Gitlab Shell contributions + +### Check + +Checks if GitLab API access and redis via internal API can be reached: + + make check + +### Compile + +Builds the `gitlab-shell` binaries, placing them into `bin/`. + + make compile + +### Install + +Builds the `gitlab-shell` binaries and installs them onto the filesystem. The +default location is `/usr/local`, but can be controlled by use of the `PREFIX` +and `DESTDIR` environment variables. + + make install + +### Setup + +This command is intended for use when installing GitLab from source on a single +machine. In addition to compiling the gitlab-shell binaries, it ensures that +various paths on the filesystem exist with the correct permissions. Do not run +it unless instructed to by your installation method documentation. + + make setup + + +### Testing + +Run tests: + + bundle install + make test + +Run gofmt: + + make verify + +Run both test and verify (the default Makefile target): + + bundle install + make validate + +### Gitaly + +Some tests need a Gitaly server. The +[`docker-compose.yml`](./docker-compose.yml) file will run Gitaly on +port 8075. To tell the tests where Gitaly is, set +`GITALY_CONNECTION_INFO`: + + export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}' + make test + +If no `GITALY_CONNECTION_INFO` is set, the test suite will still run, but any +tests requiring Gitaly will be skipped. They will always run in the CI +environment. + +### Logging Guidelines + +In general, it should be possible to determine the structure, but not content, +of a gitlab-shell or gitlab-sshd session just from inspecting the logs. Some +guidelines: + +- We use [`gitlab.com/gitlab-org/labkit/log`](https://pkg.go.dev/gitlab.com/gitlab-org/labkit/log) + for logging functionality +- **Always** include a correlation ID +- Log messages should be invariant and unique. Include accessory information in + fields, using `log.WithField`, `log.WithFields`, or `log.WithError`. +- Log success cases as well as error cases +- Logging too much is better than not logging enough. If a message seems too + verbose, consider reducing the log level before removing the message. |