contributing.md 3.24 KB
Newer Older
Simon Kirsten's avatar
Simon Kirsten committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Contributing

It is recommended to develop with [Visual Studio Code](https://code.visualstudio.com/) and make use of the git integration and the many extensions available.

## Documentation
> `mkdocs.yml`, `docs/`

The documentation is written in Markdown and built using [MkDocs](https://www.mkdocs.org/), the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme and several extensions (see `mkdocs.yml`).

Local development (requires python):
``` bash
pip install mkdocs
pip install mkdocs-material
mkdocs serve # starts a dev server
```

CI pipeline: `.gitlab-ci-docs.yml`

## Server
> `go.mod`, `go.sum`, `cmd/`, `internal/`, `pkg/`

Simon Kirsten's avatar
Simon Kirsten committed
22
The Stream Server is written in [Go](https://golang.org). It uses [Go Modules](https://github.com/golang/go/wiki/Modules).
Simon Kirsten's avatar
Simon Kirsten committed
23
24
`go.mod` and `go.sum` are for the module system to ensure [Reproducible builds](https://reproducible-builds.org/).

Simon Kirsten's avatar
Simon Kirsten committed
25
The `cmd/` directory contains only the `stream-server` command. The code of the server is in `internal/server` and the static files for the playback website in `internal/static`.  
Simon Kirsten's avatar
Simon Kirsten committed
26
27
`pkg/` contains project independent code to access the Twitch API. This separation is done in accordance to the [Standard Go Project Layout](https://github.com/golang-standards/project-layout).

28
29
30
31
32
33
34
35
36
37
38
39
Local development (requires go 1.13 and a Twitch client id):

=== "bash"
    ``` bash linenums="1"
    env TWITCH_CLIENT_ID="your client id here" go run ./cmd/stream-server
    ```

=== "PowerShell"
    ``` PowerShell linenums="1"
    $env:TWITCH_CLIENT_ID="your client id here"
    go run .\cmd\stream-server
    ```
Simon Kirsten's avatar
Simon Kirsten committed
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

CI pipeline: `.gitlab-ci-server.yml`

## Versioning
> `CHANGELOG.md`

The project uses [Semantic Versioning](https://semver.org) prefixed with an `v`.

CI pipeline: `.gitlab-ci.yml`

## GitLab

Everybody can contribute code by opening merge requests. Users with role *Developer* can also directly push to master.  
This allows interested students to work on master and make use of the CI pipeline but only *Maintainers* can create version tags. These tags are protected and will trigger an deploy to GitLab Pages by `.gitlab-ci-pages.yml`. This means that only a *Maintainer* can update the live documentation and the downloads.  
This is done to prevent abuse e.g. distributing malware.

### How a Maintainer should publish a new version

1. In GitLab --> Repository --> Compare - review the changes between *master* and the latest version tag (bottom of the list).

2. If everything is okay and no malicious code is found update the CHANGELOG.md with the new version and a short changelog. Maybe even link to issues or merge requests.

3. Commit (name it `Updated CHANGELOG to vX.X.X`), push the changes and check if the CI pipeline succeeds.  
  If the pipeline fails it means there are still errors in the server or the docs.

4. *Optionally for additional testing:* The artifacts of the pipeline can be manually tested.

5. In GitLab --> Repository --> Tags create a new tag from master. The version should be the same as in the changelog and the commit message.

6. After the pipeline for the tag is finished the documentation and downloads should update after some time.  
  Note that google needs some time to crawl and virus scan the executables so until that happens chrome will display a warning when downloading.