### Background The technical writing team has a suite of linting configuration to maintain the quality of documentation. These rules check both language issues and syntax issues that could affect rendering of <https://docs.gitlab.com>. - markdownlint: Markdown syntax linting. - Configuration file: [`.markdownlint-cli2.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint-cli2.yaml) - Custom rules in: [`doc/.markdownlint`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.markdownlint) - Vale: Language and syntax linting. - Configuration file: [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) - All rules are custom, defined with output templates in [`doc/.vale`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale). They are separated into two groups: - `gitlab_base`: Mostly language-focused lint rules to ensure we follow our documentation style guide. - `gitlab_docs`: Mostly syntax-focused lint rules to ensure our docs site renders correctly. For both markdownlint and Vale, these configuration files are present in every repository with documentation files published on the docs site, so that linting can run locally from the CLI (with lefthook, for example), or with editor extensions, like: - https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode - https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint ### Problem to solve All updates and custom rules are developed in the `gitlab` project first. Then they need to be pushed out to all other projects that we source docs from. This is a very manual and tedious process for the technical writing team, with no automation available. For example, a recent effort to sync all the projects together again shows how much work was required, but also that every project was running a slightly different version of the rules: - https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6352+s - https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/9084+s - https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/4773+s - https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/merge_requests/1379+s - https://gitlab.com/gitlab-org/cli/-/merge_requests/2807+s This list of projects could increase in the future as well. Additionally, there are many projects that also use some version our linting configuration, but which are not actively maintained by the technical writing team. At least count, at least 11 projects, which all use our lint configuration in their own ways. - https://docs.gitlab.com/development/documentation/testing/#supported-projects So we need a better process for updating, releasing and sharing our linting configuration. ### Requirements We must be able to release versioned packages that contain our latest linting configuration. The requirements: Strict: - Use GitLab features as much as possible. - Have a single source of truth for all lint configuration. - Compatible with automation like [Renovate bot](https://gitlab.com/gitlab-org/frontend/renovate-gitlab-bot) so that MRs with updated config can be created automatically. For example: https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/merge_requests/1816+ - Enable non-TW team members to make use of our linting configuration in other GitLab projects as well. - Should work with both editor plugins and CLI integrations like lefthook. Idea: - Could it be possible to continue storing rules in `gitlab`, and the package project just fetches them, packages them, and releases them? Nice to have: - Allow only subsets to be fetched, like just `markdownlint`, or just `gitlab_docs` or `gitlab_base` from Vale. For example, localization only uses `gitlab_docs`, and some side projects that aren't published on the docs site use only `gitlab_base`. - Be fetchable and usable in CI/CD pipelines for projects that don't need the lint config in the repo. - Enable the public to use our linting configuration in any project, like any other dependency. ### Proposals The solution proposals: - https://gitlab.com/gitlab-org/technical-writing/gitlab-documentation-styles - https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/merge_requests/1832+ ### Potential iterations: Assuming we follow semver from the start, even during very early development: - 0.0.X: Very early development work. - No requirement that it works fully. - Used to build and test the project, processes, pipeline, tooling, etc. - Can be used to validate that packages get deployed to the correct paths, that tests fail and prevent bad releases appropriately, etc. - Can make as many 0.0.X releases as we want during this phase. - 0.1.X -> 0.X.X: Early testable development releases. - The package may not include all the rules, but the content that is included is expected to work in a limited way. - Rules configuration can be just copied directly into the project, no need to fetch from `gitlab`. - To be used by `@gitlab-org/technical-writing/tw-docops` for local testing, as well as initial test pipelines (for example in `docs-gitlab.com` or other project we control like TW team tasks). - Initial base documentation added. - Later releases should be fully functional and could be tested with renovate or similar (again in our own projects). - Can consider testing additional feature/options at this stage, like ability to fetch and use only partial rules (only markdownlint, only Vale, etc). - 1.0.0-preX: Early release: - Test in production repos like `charts`, `omnibus`, etc... right up to `gitlab`. - Documentation should be completed (dev docs for maintenance too). - 1.0.0: Public release - Should be fully functional, and we should be comfortable not just using in our own projects, but also sharing this with the wider public. - 1.X.X (Future releases): When time allows, we can consider expanding functionality: - Fetching rules from `gitlab` instead of hosting in the project. - Building and releasing container images tied to the rules package versions. - Releasing a CI/CD component for easy docs-only linting. ### Other links/references <!-- E.g. related GitLab issues/MRs -->