diff --git a/configs/contributing.sidebar.json b/configs/contributing.sidebar.json index eded96a4..5aab953e 100644 --- a/configs/contributing.sidebar.json +++ b/configs/contributing.sidebar.json @@ -11,6 +11,10 @@ "title": "Unikraft", "path": "/docs/contributing/unikraft" }, + { + "title": "Documentation", + "path": "/docs/contributing/docs" + }, { "title": "Review Process", "path": "/docs/contributing/review-process" diff --git a/content/docs/contributing/docs.mdx b/content/docs/contributing/docs.mdx new file mode 100644 index 00000000..6fdec579 --- /dev/null +++ b/content/docs/contributing/docs.mdx @@ -0,0 +1,277 @@ +--- +title: Contributing to Documentation +--- + +## Documentation + +As with the other parts of Unikraft, we welcome contributions to the [documentation repository](https://github.com/unikraft/docs). +Documentation is written using [MDX](https://mdxjs.com/), since it make it easy to use `JSX` components. + +We follow the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) for contributions. +Submit new content, corrections and improvements to documentation as pull requests (PRs) that we will then review and approve in the documentation. +You can add entire sections if you think a topic is missing or update existing ones with missing information. + +You can also open up [an issue](https://github.com/unikraft/docs/issues) to signal a problem or a missing part in the documentation that you request someone to fix. + +We use English as the documentation language. +Please proofread your text before submitting a pull request. + +Write each sentence on a new line, since it make the content easy to review and modify. +This way, changing one sentence only affects one line in the source code, and it is easier to follow the content and the reviewes. + +Prefer using the 1st person plural for consistency across the entire repository. +Use phrases like "we run the command / app", "we look at the source code", "we provide support". + +### Content Layout + +The content has the following structure: + +```text +content +|-- blog/ # Blog posts, -.md +|-- community/ # Community related content (events, general information, etc.) +|-- docs/ # Unikraft documentation, split by categories into subdirectories +|-- guides/ # Short and on point guides, good for getting started +|-- hackathons/ # Hackathon landing pages +|-- imprint.md +|-- privacy.md +`-- releases/ # Unikraft releases summaries +``` + +### Testing Changes + +Before you submit your changes for review, please make sure you have tested them thoroughly. +You can build and deploy the site locally, following [the instructions below](/docs/contributing/docs/#building-the-website). +You can also validate your changes for common issues using the [`super-linter`](https://github.com/github/super-linter), following the [instructions below](docs/contributing/docs/#using-the-linter). +Please also do a spell check on your changes. +Most text editors should be able to do that by themselves, [here's how you do it in `Vim`](https://thoughtbot.com/blog/vim-spell-checking). + +#### Building the Website + +You can build the website inside a Docker environment or natively. +Building inside a Docker environment is **strongly recommended**, since you will work in the same environment as the deployed website. + +#### Building the Website Inside a Docker Environment + +You can build the site inside a Docker environment. +For this, you will need to install Docker-CE. +You can do that by following the instructions [here](https://github.com/docker/docker-install), or by running: + +```console +curl -fsSL https://get.docker.com/ | sh +``` + + +Building the site inside a Docker environment is highly recommended, since you will work in the same environment as the deployed site, so there will be no errors regarding packages version or filesystem layout. + + +To deploy the site, run (in the directory of the repository clone): + +```console +docker build -t ghcr.io/unikraft/docs:base --target base . + +docker run -it --rm -v $(pwd):/docs -w /docs -p 3000:3000 --entrypoint sh ghcr.io/unikraft/docs:base + +# The commands below should be used in the docker container + +yarn install +yarn run dev +``` + +You may need admin privileges to run the first 2 commands. +Open up your browser and point to http://localhost:3000 to check the deployed documentation website. + +#### Building the Website Natively + +You can also build the site natively. +For a native build, you need to install `node`. +You can do it by following the instructions [here](https://nodejs.org/en/download). + + +This may lead to errors due to different `node` versions or other environment problems. +These problems can be avoided by building the website inside a Docker environment. + + +Then, to build and deploy the site, run: + +```console +yarn install +yarn run dev +``` + +As above, open up your browser and point to http://localhost:3000 to check the deployed documentation website. + +#### Using the Linter + +To automate a big part of the reviewing process, we use the [`super-linter`](https://github.com/github/super-linter) on the `docs` repository. +It runs as a GitHub action on every time you do a push, checking all the changed files. + + + +If you click on `Details`, you can see the full linter output. +The most relevant part is under the `Lint Code Base` section, where you can find the full error messages and the line that generated the error. + + + +Since the linter checks the entire file, you may find yourself with a lot of errors from lines that you did not modify. +Please make sure that the errors are not caused by the lines that you added or modified. +If you have the time to add a commit to your pull request, that fixes all the linting errors within the modified files, we will be forever grateful :pray: + +#### Running the Linter Locally + +You can also run the linter locally, before creating the pull request. +[`super-linter`](https://github.com/github/super-linter) is actually a collection of linters; +for a local run, you need to install and then run the required linters. + +For the Unikraft documentation repository, used and useful linters are: + +- [`markdown-cli`](https://github.com/igorshubovych/markdownlint-cli#readme) +- [`textlint`](https://textlint.github.io/) +- [`jscpd`](https://github.com/kucherenko/jscpd) + +To run the `super-linter` locally, follow the instructions from [here](https://github.com/github/super-linter/blob/main/docs/run-linter-locally.md). +Note that this will require quite a lot of storage, since it will pull the `super-linter` Docker image. + +You will need to install Docker, following the [official documentation](https://docs.docker.com/install/). +After that, pull the latest container by running: + +```console +docker pull github/super-linter:latest +``` + +To run the `super-linter` on a given directory, use a command similar to: + +```console +docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true -v /path/to/directory/to/check:/tmp/lint github/super-linter +``` + +This will start a docker container that will run the `super-linter` checks on the given directory: + +```text +-------------------------------------------------------------------------------- +2022-12-29 07:50:55 [INFO] --------------------------------------------- +2022-12-29 07:50:55 [INFO] --- GitHub Actions Multi Language Linter ---- +2022-12-29 07:50:55 [INFO] - Image Creation Date:[2022-12-26T16:46:33Z] +2022-12-29 07:50:55 [INFO] - Image Revision:[154522b380449499473f75d46f3796e23ebc1d2e] +2022-12-29 07:50:55 [INFO] - Image Version:[154522b380449499473f75d46f3796e23ebc1d2e] +2022-12-29 07:50:55 [INFO] --------------------------------------------- +2022-12-29 07:50:55 [INFO] --------------------------------------------- +2022-12-29 07:50:55 [INFO] The Super-Linter source code can be found at: +2022-12-29 07:50:55 [INFO] - https://github.com/github/super-linter +2022-12-29 07:50:55 [INFO] --------------------------------------------- +2022-12-29 07:50:55 [INFO] -------------------------------------------- +[...] +``` + +A sample run, while in the root directory of this documentation repository, is: + +```console +docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true -v $(pwd)/content/docs/contributing/:/tmp/lint/ github/super-linter +``` + +You can also run each linter separately, since it will require less storage space. +To run the linters, you will need to install the [`markdown-cli`](https://github.com/igorshubovych/markdownlint-cli), [`textlint`](https://textlint.github.io/docs/getting-started.html) and [`jscpd`](https://github.com/kucherenko/jscpd#installation) tools: + +```console +npm install markdownlint-cli +npm install textlint +npm install jscpd +``` + +Note that it's likely that these linters require a more recent version of `node` than the default package installation. +Install the most recent one using [`nvm`](https://github.com/nvm-sh/nvm). +First, install `nvm` using [the instructions here](https://github.com/nvm-sh/nvm). +Then install the most recent version of `node` and follow the instructions: + +```console +nvm install node +# Follow instructions shown by the above command. +nvm use node +node --version # Check node version. +``` + +The `textlinter` will require installation of rules. +You can find a list of rules [here](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule). + +```console +npm install textlint-rule-terminology +npm install textlint-rule-no-todo +``` + +Use the linters with `npx` from the documentation directory: + +```console +npx markdownlint --config .github/workflows/config/config.json --rules .github/workflows/rules/rules.js path/to/markdown/file.mdx +npx textlint --config .github/workflows/.textlintrc --rule path/to/markdown/file.mdx +npx jscpd # Typically a directory +``` + +For example: + +```console + npx markdownlint --config .github/workflows/config/config.json --rules .github/workflows/rules/rules.js content/docs/contributing/*.mdx +``` + +```text +_index.md:14:187 MD033/no-inline-html Inline HTML [Element: a] +blog-case-studies.mdx:10 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] +code-of-conduct.mdx:69 MD104/one line per sentence one line (and only one line) per sentence [Expected one sentence per line. Multiple end of sentence punctuation signs found on one line!] +code-of-conduct.mdx:82:1 MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 1] +code-of-conduct.mdx:85:1 MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 1] +[...] +``` + +```console +npx textlint --config .github/workflows/.textlintrc content/docs/contributing/code-of-conduct.mdx +``` + +```text +[...]/docs/content/docs/contributing/code-of-conduct.mdx + 61:66 ✓ error Incorrect usage of the term: “e-mail”, use “email” instead terminology + +✖ 1 problem (1 error, 0 warnings) +✓ 1 fixable problem. +Try to run: $ textlint --fix [file] +``` + +```console +npx jscpd content/docs/contributing/code-of-conduct.mdx +``` + +```text ++--------------------------------------------------------------------------------------------------------------+ +| Format | Files analyzed | Total lines | Total tokens | Clones found | Duplicated lines | Duplicated tokens | +|----------+----------------+-------------+--------------+--------------+------------------+-------------------| +| url | 1 | 4 | 28 | 0 | 0 (0%) | 0 (0%) | +|----------+----------------+-------------+--------------+--------------+------------------+-------------------| +| markdown | 1 | 130 | 1470 | 0 | 0 (0%) | 0 (0%) | +|----------+----------------+-------------+--------------+--------------+------------------+-------------------| +| Total: | 2 | 134 | 1498 | 0 | 0 (0%) | 0 (0%) | ++--------------------------------------------------------------------------------------------------------------+ +Found 0 clones. +Detection time:: 41.945ms +``` + +### Reviewing Changes + +If you are assigned as a reviewer to a pull request (PR), please follow the [testing steps](docs/contributing/docs/#testing-changes) and make sure everything looks good. + +The review may go through a set of back-and-forth steps between the author and the reviewer before the reviewer marks the PR as approved. +As a reviewer, when you consider the process complete, you must add a signature, in the same way that the author has. +This is done by writing adding a `Reviewed-by` line as part of your approval message in the GitHub review interface: + +```text +Reviewed-by: Your Name +``` diff --git a/static/assets/imgs/github-super-linter-output.png b/public/assets/imgs/github-super-linter-output.png similarity index 100% rename from static/assets/imgs/github-super-linter-output.png rename to public/assets/imgs/github-super-linter-output.png diff --git a/static/assets/imgs/github-super-linter.png b/public/assets/imgs/github-super-linter.png similarity index 100% rename from static/assets/imgs/github-super-linter.png rename to public/assets/imgs/github-super-linter.png