Skip to content

Contributing

It is recommended to develop with Visual Studio Code 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, the Material for MkDocs theme and several extensions (see mkdocs.yml).

Local development (requires python): 

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/

The Stream Server is written in Go. It uses Go Modules. go.mod and go.sum are for the module system to ensure Reproducible builds.

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.
pkg/ contains project independent code to access the Twitch API. This separation is done in accordance to the Standard Go Project Layout.

Local development (requires go 1.13 and a Twitch client id):

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

1
2
$env:TWITCH_CLIENT_ID="your client id here"
go run .\cmd\stream-server

CI pipeline: .gitlab-ci-server.yml

Versioning

CHANGELOG.md

The project uses Semantic Versioning 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.

Last update: June 16, 2020