Loading service/documentation.md +34 −0 Original line number Diff line number Diff line Loading @@ -39,6 +39,11 @@ To make changes there, just clone and push to this git repository: git clone git@gitlab.torproject.org:tpo/tpa/wiki-replica.git Make changes, and push. Note that a GitLab CI pipeline will check your changes and might warn you if you work on a file with syntax problems. Feel free to ignore those warnings that were already present, but do be careful at not adding new ones. Ideally, you should also setup linting locally, see below. ## Local linting configuration Loading Loading @@ -212,6 +217,35 @@ considered the editor of the wiki, but any other contributors is strongly encouraged to contribute to the knowledge accumulating in the wiki. ### Linting There is a basic linting check deployed in GitLab CI on the [wiki replica](https://gitlab.torproject.org/tpo/tpa/wiki-replica), which will run on pull requests and normal pushes. Naturally, it will not run when someone edits the wiki directly, as the replica does not pull automatically from the wiki (because of limitations in the free GitLab mirror implementation). Those checks are setup in the `.gitlab-ci.yml` file. There is a basic `test` job that will run whenever a Markdown (`.md`) file gets modified. There is a rather convoluted pipeline to ensure that it runs *only* on those files, which requires a separate Docker image and job to generate that file list, because the [`markdownlint/markdownlint` Docker image](https://hub.docker.com/r/markdownlint/markdownlint) doesn't ship with git (see [this discussion for details](https://forum.gitlab.com/t/ci-cd-pipeline-get-list-of-changed-files/26847/16?u=anarcat)). There's a separate job (`testall`) which runs every time and checks *all* markdown files. Because GitLab has this... [unusual syntax](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents) for triggering the automatic table of contents display (`[[_TOC_]]`), we need to go through some hoops to silence those warnings. This implies that the `testall` job will always fail, as long as we use that specific macro. Those linting checks could eventually be expanded to do more things, like spell-checking and check for links outside of the current document. See the [alternatives considered](#alternatives-considered) section for a broader discussion on the next steps here. ## Issues There is no issue tracker specifically for this project, [File][] or Loading Loading
service/documentation.md +34 −0 Original line number Diff line number Diff line Loading @@ -39,6 +39,11 @@ To make changes there, just clone and push to this git repository: git clone git@gitlab.torproject.org:tpo/tpa/wiki-replica.git Make changes, and push. Note that a GitLab CI pipeline will check your changes and might warn you if you work on a file with syntax problems. Feel free to ignore those warnings that were already present, but do be careful at not adding new ones. Ideally, you should also setup linting locally, see below. ## Local linting configuration Loading Loading @@ -212,6 +217,35 @@ considered the editor of the wiki, but any other contributors is strongly encouraged to contribute to the knowledge accumulating in the wiki. ### Linting There is a basic linting check deployed in GitLab CI on the [wiki replica](https://gitlab.torproject.org/tpo/tpa/wiki-replica), which will run on pull requests and normal pushes. Naturally, it will not run when someone edits the wiki directly, as the replica does not pull automatically from the wiki (because of limitations in the free GitLab mirror implementation). Those checks are setup in the `.gitlab-ci.yml` file. There is a basic `test` job that will run whenever a Markdown (`.md`) file gets modified. There is a rather convoluted pipeline to ensure that it runs *only* on those files, which requires a separate Docker image and job to generate that file list, because the [`markdownlint/markdownlint` Docker image](https://hub.docker.com/r/markdownlint/markdownlint) doesn't ship with git (see [this discussion for details](https://forum.gitlab.com/t/ci-cd-pipeline-get-list-of-changed-files/26847/16?u=anarcat)). There's a separate job (`testall`) which runs every time and checks *all* markdown files. Because GitLab has this... [unusual syntax](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents) for triggering the automatic table of contents display (`[[_TOC_]]`), we need to go through some hoops to silence those warnings. This implies that the `testall` job will always fail, as long as we use that specific macro. Those linting checks could eventually be expanded to do more things, like spell-checking and check for links outside of the current document. See the [alternatives considered](#alternatives-considered) section for a broader discussion on the next steps here. ## Issues There is no issue tracker specifically for this project, [File][] or Loading
