chore: Update repo README and CONTRIBUTING section (#1439)

* Update README.md

* Update CONTRIBUTING section

Add more details about where to make changes, apply-patch script, and creating a new release

* Update pull_request_template.md

* Fix typo

Author: heitortsergent

.github/pull_request_template.md

@@ -18,9 +18,10 @@ Please fill in this template:
 Select one of these and delete the others:
 
 If updating the documentation for the most recent release of k6: 
-- [ ] I have made my changes in the `docs/sources/v{most_recent_release}` folder of the documentation.
-- [ ] I have reflected my changes in the `docs/sources/next` folder of the documentation.
+- [ ] I have made my changes in the `docs/sources/next` folder of the documentation.
+- [ ] I have reflected my changes in the `docs/sources/v{most_recent_release}` folder of the documentation.
 - [ ] I have reflected my changes in the relevant (*e.g.*  when correcting a documentation error) folders of the previous k6 versions of the documentation.
+<!-- You can use the scripts/apply-patch scripts to help you port changes from one version folder to another. For more details, refer to [Use the `apply-patch` script](../CONTRIBUTING/README.md#use-the-apply-patch-script). -->
 
 If updating the documentation for the next release of k6:
 - [ ] I have made my changes in the `docs/sources/next` folder of the documentation.

CONTRIBUTING/README.md

@@ -10,10 +10,14 @@ When you contribute to the docs, it helps to know how things work.
     - [Before you begin](#before-you-begin)
     - [Build and preview](#build-and-preview)
 - [Write](#write)
+    - [Where to make updates](#where-to-make-updates)
+        - [Updates and fixes to the latest version of k6](#updates-and-fixes-to-the-latest-version-of-k6)
+        - [Updates and fixes to the next major release of k6](#updates-and-fixes-to-the-next-major-release-of-k6)
+    - [Use the `apply-patch` script](#use-the-apply-patch-script)
     - [Style Guides](#style-guides)
     - [Shortcodes](#shortcodes)
 - [Deploy](#deploy)
-    - [Upgrade a main release](#upgrade-a-main-release)
+- [Create a new release](#create-a-new-release)
 
 <!-- markdown-toc end -->
 
@@ -23,6 +27,7 @@ For writers, these are the most important directories:
 
 - [`docs/sources`](../docs/sources) is where the docs live.
 - `docs/sources/VERSION/shared` has Markdown files that can be reused across multiple pages by using the [`shared` shortcode](https://grafana.com/docs/writers-toolkit/write/shortcodes/#docsshared).
+- `src/data/markdown` contains the Markdown files for the legacy version of the docs, available at https://k6.io/docs. **You do not need to update these files if you're making changes to the current or next version of the docs, available at https://grafana.com/docs/k6/latest/**.
 
 ## Build locally
 
@@ -72,6 +77,55 @@ description: <summary text for search engines and social shares. Aim for 170 cha
 ---
 ```
 
+You can find the Markdown file for the docs in the [`docs/sources`](../docs/sources) folder. In that folder you'll find:
+
+- A `next` folder, which represents the docs for the next major release of k6.
+- Multiple version folders (for example, v0.47.x), which represents the docs for that specific version of k6.
+
+Depending on the type of update you need to make, you'll want to make updates to different folders.
+
+### Where to make updates
+
+#### Updates and fixes to the latest version of k6
+
+If you're making any updates or fixes that apply to the latest version of k6, you'll need to:
+
+- Update the Markdown files in the `docs/sources/next` folder.
+- Update the Markdown files in the `docs/sources/v{LATEST_VERSION}` folder.
+  - You can do this manually or by using the [`apply-patch`](../scripts/apply-patch) script from the `scripts` folder. Refer to the [Use the `apply-patch` script](#use-the-apply-patch-script) section for more details.
+
+This is to make sure that any changes you make are also brought over to the next major release version of k6.
+
+#### Updates and fixes to the next major release of k6
+
+If you're making any updates or fixes that only apply to the next major release of k6, you'll need to:
+
+- Update the Markdown files in the `docs/sources/next` folder.
+
+Once you make any changes and open a PR, and that PR is reviewed, you can merge it without having to worry about those changes showing up in the `latest` version of the docs. The `latest` version will always display the highest numbered version folder of the docs.
+
+### Use the `apply-patch` script
+
+You can use the `apply-patch script` to port changes from one version folder to another. This is especially helpful if you're making updates or fixes to the latest version of k6, and want to make sure they're also reflected in the `next` version folder.
+
+To use the script, make sure you're in the root of the k6-docs folder and run:
+
+```bash
+scripts/apply-patch <COMMIT> <SOURCE> <DESTINATION>
+```
+
+For example, if you'd like to apply the changes from your last commit, from the `docs/sources/next` folder to the `docs/sources/v0.47.x`, you can run:
+
+```bash
+scripts/apply-patch HEAD~ docs/sources/next docs/sources/v0.47.x
+```
+
+Or if you'd like to apply the changes from your previous three commits, you can run:
+
+```bash
+scripts/apply-patch HEAD~3 docs/sources/next docs/sources/v0.47.x
+```
+
 ### Style guides
 
 - k6 follows the style prescribed in the [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/), which itself inherits most of its rules from the [Google developer documentation style guide](https://developers.google.com/style).
@@ -86,10 +140,22 @@ Refer to [Writers' Toolkit, Write documentation](https://grafana.com/docs/writer
 
 Once a PR is merged to the main branch, if there are any changes made to the `docs/sources` folder, the GitHub Action [`publish-technical-documentation.yml`](https://github.com/grafana/k6-docs/blob/main/.github/workflows/publish-technical-documentation.yml) will sync the changes with the grafana/website repository, and the changes will be deployed to production soon after.
 
-### Upgrade a main release
+## Create a new release
 
->  #### ⚠️ Versions
+>  ### ⚠️ Versions
 >
-> Versions follow the same major and minor numbers as github.com/grafana/k6.
+> Versions follow the same major numbers as github.com/grafana/k6.
+
+When a new major version of k6 is released, you need to create a new folder for it in the [`docs/sources`](../docs/sources) folder.
+
+The process for creating a new release should be:
+
+- Review any open PRs that relate to the next major release, and merge them if they have been reviewed and approved.
+- `git pull` the latest version of the k6-docs repository.
+- In the `docs/sources` folder:
+  - Duplicate the `next` folder.
+  - Rename the `next copy` folder to match the next major release version. For example, if the next release is `v0.48`, the folder should be renamed to `v0.48.x`.
+- Build the docs locally to check that the latest version matches the new version folder.
+- Commit and push your changes.
 
-TODO: Add step-by-step instructions for creating a new major version release.
+Once your changes are automatically deployed, you should be able to see the new version live by going to https://grafana.com/docs/k6/latest/.

README.md

@@ -12,6 +12,7 @@ Some key facts:
 - The docs are written in Markdown and built with Hugo.
 - The [Contributor's guide](./CONTRIBUTING) has meta-documentation about building locally, using special components and styling, deploying, troubleshooting, and more.
 - We have a [Code of conduct](https://github.com/grafana/k6-docs/blob/main/CODE_OF_CONDUCT.md).
+- We follow the Grafana Style Guide, and you can find more information about it in the [Writers' Toolkit](https://grafana.com/docs/writers-toolkit/).
 
 ## Contributing
 
@@ -24,13 +25,15 @@ Markdown files for the documentation are located in the [`docs/sources/`](docs/s
 
 For small changes and spelling fixes, the GitHub UI is the most convenient way to contribute.
 For larger contributions, consider running the project locally to see how the changes look like before making a pull request.
- 
+
 The following docs cover the different stages of the writing workflow:
 
 - [Local development](#local-development). For any large changes, being able to see a preview of the site can help make sure things are rendered correctly, and spot any issues before they're deployed to production.
 - [Writers' Toolkit](https://grafana.com/docs/writers-toolkit/). Learn more about the Grafana writing style guide, front matter properties, how to upload and add images, and much more.
 - [Preview and deploy](./CONTRIBUTING#deploy). Changes made to the files inside of `docs/sources` are automatically deployed to production once they're merged to the main branch.
 
+For more details, refer to the [CONTRIBUTING](./CONTRIBUTING/README.md) section.
+
 ## Local development
 
 ### Before you begin
@@ -64,4 +67,4 @@ View documentation locally:
                                                            Press Ctrl+C to stop the server
 ```
 
-Go to http://localhost:3002/docs/k6/, and you should be able to see a preview of the docs.
+Go to http://localhost:3002/docs/k6/, and you should be able to see a preview of the docs.