diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b643a46ddf..94d664954f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,6 +14,8 @@ LIDs must be created as a pull request using [this template](docs/sources/commun ## Pull Request Prerequisites/Checklist +**NOTE:** The Loki team has adopted the use of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. + 1. Your PR title is in the form `: Your change`. 1. It does not end the title with punctuation. It will be added in the changelog. 1. It starts with an imperative verb. Example: Fix the latency between System A and System B. @@ -36,6 +38,8 @@ LIDs must be created as a pull request using [this template](docs/sources/commun Please document clearly what changed AND what needs to be done in the upgrade guide. +**NOTE:** A member of the Loki repo maintainers must approve and run the continuous integration (CI) workflows for community contributions. + ## Setup A common problem arises in local environments when you want your module to use a locally modified dependency: @@ -157,3 +161,8 @@ To get a local preview of the documentation: Then you can go to Docker Desktop settings and open the resources, add the temporary directory path `/tmp`. > Note that `make docs` uses a lot of memory. If it crashes, increase the memory allocated to Docker and try again. + +Also note that PRs are merged to the main branch. If your changes need to be immediately published to the latest release, you must add the appropriate backport label to your PR, for example, `backport-release-2.9.x`. If the changes in your PR can be automatically backported, the backport label will trigger GrafanaBot to create the backport PR, otherwise you will need to create a PR to manually backport your changes. + +* [Latest release](https://grafana.com/docs/loki/latest/) +* [Upcoming release](https://grafana.com/docs/loki/next/), at the tip of the main branch diff --git a/docs/README.md b/docs/README.md index a3aa4414ad..569889c2d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ Some key things to know about the Loki documentation source: - While you can view the documentation in GitHub, GitHub does not render the images or links correctly and cannot render the Hugo specific shortcodes. To read the Loki documentation, see the [Documentation Site](https://grafana.com/docs/loki/latest/). - If you have a trivial fix or improvement, go ahead and create a pull request. - If you plan to do something more involved, for example creating a new topic, discuss your ideas on the relevant GitHub issue. +- Pull requests are merged to main, and published to [Upcoming release](https://grafana.com/docs/loki/next/). If your change needs to be published to the [Latest release](https://grafana.com/docs/loki/latest/) before the next Loki release (that is, it needs to be published immediately), add the appropriate backport label to your PR. ## Contributing @@ -26,16 +27,26 @@ If you have a GitHub account and you're just making a small fix, for example fix 2. Click the pencil icon. 3. Enter your changes. 4. Click **Commit changes**. GitHub creates a pull request for you. -5. If this is your first contribution to the Loki repository, you will need to sign the Contributor License Agreement (CLA) before your PR can be accepted. -6. Add the `type/docs` label to identify your PR as a docs contribution. -7. If your contribution needs to be added to the current release or previous releases, apply the appropriate `backport` label. You can find more information about backporting in the [Writers' toolkit](https://grafana.com/docs/writers-toolkit/review/backporting/). +5. The Loki team uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. Make sure your commit messages for doc updates start with `doc:`. +6. If this is your first contribution to the Loki repository, you will need to sign the Contributor License Agreement (CLA) before your PR can be accepted. +**NOTE:** A member of the Loki repo maintainers must approve and run the continuous integration (CI) workflows for community contributions. +7. Add the `type/docs` label to identify your PR as a docs contribution. This helps the documentation team track our work. +8. If your contribution needs to be added to the current release or previous releases, apply the appropriate `backport` label. You can find more information about backporting in the [Writers' toolkit](https://grafana.com/docs/writers-toolkit/review/backporting/). For larger contributions, for example documenting a new feature or adding a new topic, consider running the project locally to see how the changes look like before making a pull request. -The docs team has created a [Writer's Toolkit](https://grafana.com/docs/writers-toolkit/) that documents how we write documentation at Grafana Labs. The Writer's toolkit contains information about how we structure documentation at Grafana, including templates for different types of topics, information about Hugo shortcodes that extend markdown to add additional features, and information about linters and other tools that we use to write documentation. The Writers' Toolkit also includes our [Style Guide](https://grafana.com/docs/writers-toolkit/write/style-guide/). +The docs team has created a [Writers' Toolkit](https://grafana.com/docs/writers-toolkit/) that documents how we write documentation at Grafana Labs. Writers' Toolkit contains information about how we structure documentation at Grafana, including templates for different types of topics, information about Hugo shortcodes that extend markdown to add additional features, and information about linters and other tools that we use to write documentation. Writers' Toolkit also includes our [Style Guide](https://grafana.com/docs/writers-toolkit/write/style-guide/). Note that in Hugo the structure of the documentation is based on the folder structure of the documentation repository. The URL structure is generated based on the folder structure and file names. Try to avoid moving or renaming files, as this will break cross-references to those files. If you must move or rename files, run `make docs` as described below to find and fix broken links before you submit your pull request. +## Shared content + +**NOTE:** As of Loki/GEL 3.0, there will be shared files between the Loki docs and the GEL docs. The Grafana Enterprise Logs documentation will pull in content from the Loki repo when publishing the GEL docs. Files that are shared between the two doc sets will contain a comment indicating that the content is shared. + +For more information about shared content, see the [reuse content](https://grafana.com/docs/writers-toolkit/write/reuse-content/) section of the Writers' Toolkit. + +For more information about building and testing documentation, see the [build and review](https://grafana.com/docs/writers-toolkit/review/) section of the Writers' Toolkit. + ## Testing documentation Loki uses the static site generator [Hugo](https://gohugo.io/) to generate the documentation. The Loki repository uses a continuous integration (CI) action to sync documentation to the [Grafana website](https://grafana.com/docs/loki/latest). The CI is triggered on every merge to main in the `docs` subfolder.