Skip to content

Commit 49e8401

Browse files
author
Patrick Bajao
committed
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 parents 40295a0 + 0c7ff7f commit 49e8401

File tree

2 files changed

+96
-76
lines changed

2 files changed

+96
-76
lines changed

‎README.md‎

Lines changed: 2 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -42,81 +42,6 @@ Download and install the current version of Go from https://golang.org/dl/
4242
We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
4343
of supporting the current stable version and the previous two major versions.
4444

45-
## Check
46-
47-
Checks if GitLab API access and redis via internal API can be reached:
48-
49-
make check
50-
51-
## Compile
52-
53-
Builds the `gitlab-shell` binaries, placing them into `bin/`.
54-
55-
make compile
56-
57-
## Install
58-
59-
Builds the `gitlab-shell` binaries and installs them onto the filesystem. The
60-
default location is `/usr/local`, but can be controlled by use of the `PREFIX`
61-
and `DESTDIR` environment variables.
62-
63-
make install
64-
65-
## Setup
66-
67-
This command is intended for use when installing GitLab from source on a single
68-
machine. In addition to compiling the gitlab-shell binaries, it ensures that
69-
various paths on the filesystem exist with the correct permissions. Do not run
70-
it unless instructed to by your installation method documentation.
71-
72-
make setup
73-
74-
75-
## Testing
76-
77-
Run tests:
78-
79-
bundle install
80-
make test
81-
82-
Run gofmt:
83-
84-
make verify
85-
86-
Run both test and verify (the default Makefile target):
87-
88-
bundle install
89-
make validate
90-
91-
### Gitaly
92-
93-
Some tests need a Gitaly server. The
94-
[`docker-compose.yml`](./docker-compose.yml) file will run Gitaly on
95-
port 8075. To tell the tests where Gitaly is, set
96-
`GITALY_CONNECTION_INFO`:
97-
98-
export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
99-
make test
100-
101-
If no `GITALY_CONNECTION_INFO` is set, the test suite will still run, but any
102-
tests requiring Gitaly will be skipped. They will always run in the CI
103-
environment.
104-
105-
## Logging Guidelines
106-
107-
In general, it should be possible to determine the structure, but not content,
108-
of a gitlab-shell or gitlab-sshd session just from inspecting the logs. Some
109-
guidelines:
110-
111-
- We use [`gitlab.com/gitlab-org/labkit/log`](https://pkg.go.dev/gitlab.com/gitlab-org/labkit/log)
112-
for logging functionality
113-
- **Always** include a correlation ID
114-
- Log messages should be invariant and unique. Include accessory information in
115-
fields, using `log.WithField`, `log.WithFields`, or `log.WithError`.
116-
- Log success cases as well as error cases
117-
- Logging too much is better than not logging enough. If a message seems too
118-
verbose, consider reducing the log level before removing the message.
119-
12045
## Rate Limiting
12146

12247
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)
13358

13459
## Contributing
13560

136-
See [CONTRIBUTING.md](./CONTRIBUTING.md).
61+
- See [CONTRIBUTING.md](./CONTRIBUTING.md).
62+
- See the [beginner's guide](doc/beginners_guide.md).
13763

13864
## License
13965

‎doc/beginners_guide.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
stage: Create
3+
group: Source Code
4+
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
5+
---
6+
7+
# Beginner's guide to GitLab Shell contributions
8+
9+
## Check
10+
11+
Checks if GitLab API access and Redis via internal API can be reached:
12+
13+
```shell
14+
make check
15+
```
16+
17+
## Compile
18+
19+
Builds the `gitlab-shell` binaries, placing them into `bin/`.
20+
21+
```shell
22+
make compile
23+
```
24+
25+
## Install
26+
27+
Builds the `gitlab-shell` binaries and installs them onto the file system. The
28+
default location is `/usr/local`, but you can change the location by setting the `PREFIX`
29+
and `DESTDIR` environment variables.
30+
31+
```shell
32+
make install
33+
```
34+
35+
## Setup
36+
37+
This command is intended for use when installing GitLab from source on a single
38+
machine. It compiles the GitLab Shell binaries, and ensures that
39+
various paths on the file system exist with the correct permissions. Do not run
40+
this command unless your installation method documentation instructs you to.
41+
42+
```shell
43+
make setup
44+
```
45+
46+
## Testing
47+
48+
Run tests:
49+
50+
```shell
51+
bundle install
52+
make test
53+
```
54+
55+
Run Gofmt:
56+
57+
```shell
58+
make verify
59+
```
60+
61+
Run both test and verify (the default Makefile target):
62+
63+
```shell
64+
bundle install
65+
make validate
66+
```
67+
68+
## Gitaly
69+
70+
Some tests need a Gitaly server. The
71+
[`docker-compose.yml`](../docker-compose.yml) file runs Gitaly on port 8075.
72+
To tell the tests where Gitaly is, set `GITALY_CONNECTION_INFO`:
73+
74+
```plaintext
75+
export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
76+
make test
77+
```
78+
79+
If no `GITALY_CONNECTION_INFO` is set, the test suite still runs, but any
80+
tests requiring Gitaly are skipped. The tests always run in the CI environment.
81+
82+
## Logging Guidelines
83+
84+
In general, you can determine the structure, but not content, of a GitLab Shell
85+
or `gitlab-sshd` session by inspecting the logs. Some guidelines:
86+
87+
- We use [`gitlab.com/gitlab-org/labkit/log`](https://pkg.go.dev/gitlab.com/gitlab-org/labkit/log)
88+
for logging.
89+
- Always include a correlation ID.
90+
- Log messages should be invariant and unique. Include accessory information in
91+
fields, using `log.WithField`, `log.WithFields`, or `log.WithError`.
92+
- Log both success cases and error cases.
93+
- Logging too much is better than not logging enough. If a message seems too
94+
verbose, consider reducing the log level before removing the message.

0 commit comments

Comments
 (0)