Merge branch 'id-create-beginners-guide' into 'main'

Move code guidelines to doc/beginners_guide.md

See merge request gitlab-org/gitlab-shell!572

2 files changed, 96 insertions, 76 deletions

diff --git a/README.md b/README.md
index 1a71a79..c91bf8d 100644
--- a/README.md
+++ b/README.md
@@ -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..4022cc1
--- /dev/null
+++ b/doc/beginners_guide.md
@@ -0,0 +1,94 @@
+---
+stage: Create
+group: Source Code
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Beginner's guide to GitLab Shell contributions
+
+## Check
+
+Checks if GitLab API access and Redis via internal API can be reached:
+
+```shell
+make check
+```
+
+## Compile
+
+Builds the `gitlab-shell` binaries, placing them into `bin/`.
+
+```shell
+make compile
+```
+
+## Install
+
+Builds the `gitlab-shell` binaries and installs them onto the file system. The
+default location is `/usr/local`, but you can change the location by setting the `PREFIX`
+and `DESTDIR` environment variables.
+
+```shell
+make install
+```
+
+## Setup
+
+This command is intended for use when installing GitLab from source on a single
+machine. It compiles the GitLab Shell binaries, and ensures that
+various paths on the file system exist with the correct permissions. Do not run
+this command unless your installation method documentation instructs you to.
+
+```shell
+make setup
+```
+
+## Testing
+
+Run tests:
+
+```shell
+bundle install
+make test
+```
+
+Run Gofmt:
+
+```shell
+make verify
+```
+
+Run both test and verify (the default Makefile target):
+
+```shell
+bundle install
+make validate
+```
+
+## Gitaly
+
+Some tests need a Gitaly server. The
+[`docker-compose.yml`](../docker-compose.yml) file runs Gitaly on port 8075.
+To tell the tests where Gitaly is, set `GITALY_CONNECTION_INFO`:
+
+```plaintext
+export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
+make test
+```
+
+If no `GITALY_CONNECTION_INFO` is set, the test suite still runs, but any
+tests requiring Gitaly are skipped. The tests always run in the CI environment.
+
+## Logging Guidelines
+
+In general, you can determine the structure, but not content, of a GitLab Shell
+or `gitlab-sshd` session by 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.
+- 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 both success cases and 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.