diff --git a/STYLE.md b/STYLE.md index de1cea0be8cca50d89934a7913499fe27beb0dc7..328ca15fd5087ae34e84ed6d06fe2bef42eec61c 100644 --- a/STYLE.md +++ b/STYLE.md @@ -572,6 +572,38 @@ one of the following: * Put this element in a separate document and always refer to it using links. +## To-dos + +To-do items intended for writers, for example to fill in incomplete sections, +must follow these guidelines: + +* Always use HTML comments `<!-- -->` to prevent the to-do items or other + writer-only notes from being included in the published docs. + +* Prefix your to-dos with `TODO:` to make them easier to find. + +* Avoid `TODO` without a colon (`:`) as some IDEs, editor extensions, etc. + might require a colon. + +* Avoid `<!-- TODO: -->` without an explicit message on what there is to do. + +* If a to-do item is not to be completed before the documentation gets merged + or published, consider creating a GitLab issue. + +* Add links to relevant GitLab issues in your to-do comments. + +An example of a to-do comment with a GitLab issue follows: + +```markdown +<!-- +TODO: Update screenshots for v1.0 +https://gitlab.com/arkindex/doc/issues/99999 +--> +``` + +The [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) +extension is recommended for Visual Studio Code users. + ## Project-specific guidelines This section describes guidelines that are purely specific to the Arkindex