docs: implement versioned documentation (#3577)

.github/ISSUE_TEMPLATE/release-tracker.md

@@ -57,9 +57,14 @@ versions of ibc-go to guarantee that no regression is introduced -->
   - Add the new release.
   - Remove any tags that might not be recommended anymore.
 - [ ] Update the list of [supported release lines in README.md](https://github.com/cosmos/ibc-go#releases), if necessary.
-- [ ] (TODO: [#3522](https://github.com/cosmos/ibc-go/issues/3522)) Update docs site:
-  - [ ] Add new release branch to [`docs/versions`](https://github.com/cosmos/ibc-go/blob/main/docs/versions) file.
-  - [ ] Add `label` and `key` to `versions` array in [`config.js`](https://github.com/cosmos/ibc-go/blob/main/docs/.vuepress/config.js#L62).
+- [ ] Update docs site:
+  - [ ] If the release is occurring on the main branch, on the latest version, then run `npm run docusaurus docs:version vX.Y.Z` in the `docs/` directory. (where `X.Y.Z` is the new version number)
+  - [ ] If the release is occurring on an older release branch, then make a PR to the main branch called `docs: new release vX.Y.Z` doing the following:
+    - [ ] Update the content of the docs found in `docs/versioned_docs/version-vx.y.z` if needed. (where `x.y.z` is the previous version number)
+    - [ ] Update the version number of the older release branch by changing the version number of the older release branch in:
+      - [ ] In `docs/versions.json`.
+      - [ ] Rename `docs/versioned_sidebars/version-vx.y.z-sidebars.json`
+      - [ ] Rename `docs/versioned_docs/version-vx.y.z`
 - [ ] Bump ibc-go version in [cosmos/interchain-accounts-demo repository](https://github.com/cosmos/interchain-accounts-demo) and create a tag.
 - [ ] Update the [compatibility test matrices](https://github.com/cosmos/ibc-go/tree/main/.github/compatibility-test-matrices):
   - Add the new release.

.github/workflows/deploy-docs.yml

@@ -6,7 +6,6 @@ on:
   push:
     branches:
       - main
-      - "release/**"
     paths:
       - "docs/**"
       - .github/workflows/deploy-docs.yml

.github/workflows/link-check-config.json

@@ -4,7 +4,17 @@
       "pattern": "(localhost)"
     }
   ],
+  "replacementPatterns": [
+    {
+      "pattern": "(^\\/(architecture|event)[^#]*)(#.*|$)",
+      "replacement": "$1.md$3"
+    },
+    {
+      "pattern": "^(\\/|@site\\/)",
+      "replacement": "{{BASEURL}}/docs/"
+    }
+  ],
   "retryOn429": true,
   "retryCount": 3,
   "fallbackRetryDelay": "10s"
-}
+}

.github/workflows/link-check.yml

@@ -7,4 +7,4 @@ jobs:
     - uses: actions/checkout@v3
     - uses: gaurav-nelson/github-action-markdown-link-check@v1
       with:
-        config-file: '.github/workflows/link-check-config.json'
+        config-file: '.github/workflows/link-check-config.json'

.markdownlint.jsonc

@@ -7,4 +7,4 @@
   "MD033": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033---inline-html
   "MD036": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md036---emphasis-used-instead-of-a-heading
   "MD041": false // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041---first-line-in-a-file-should-be-a-top-level-heading
-}
+}

.markdownlintignore

@@ -1,3 +1,3 @@
 vendor
 e2e/vendor
-docs/node_modules
+docs/node_modules

CODE_OF_CONDUCT.md

@@ -8,19 +8,19 @@ In the interest of fostering an open and welcoming environment, we as contributo
 
 Examples of behavior that contributes to creating a positive environment include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 
@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <[email protected]>. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 

CONTRIBUTING.md

@@ -57,7 +57,7 @@ Please make sure to check out our [Pull request guidelines](./docs/dev/pull-requ
 - [Project structure](./docs/dev/project-structure.md)
 - [Develoment setup](./docs/dev/development-setup.md)
 - [Go style guide](./docs/dev/go-style-guide.md)
-- [Documentation guidelines](./docs/DOCS_GUIDELINES.md)
+- [Documentation guide](./docs/README.md)
 - [Writing tests](./testing/README.md)
 - [Pull request guidelines](./docs/dev/pull-requests.md)
 - [Release process](./docs/dev/release-management.md)

Makefile

@@ -152,24 +152,11 @@ godocs:
 	@echo "--> Wait a few seconds and visit http://localhost:6060/pkg/github.com/cosmos/cosmos-sdk/types"
 	godoc -http=:6060
 
-# This builds a docs site for each branch/tag in `./docs/versions`
-# and copies each site to a version prefixed path. The last entry inside
-# the `versions` file will be the default root index.html.
 build-docs:
-	@cd docs && \
-	while read -r branch path_prefix; do \
-		echo "building branch $${branch}" ; \
-		(git clean -fdx && git reset --hard && git checkout $${branch} && npm install && VUEPRESS_BASE="/$${path_prefix}/" npm run build) ; \
-		mkdir -p ~/output/$${path_prefix} ; \
-		cp -r .vuepress/dist/* ~/output/$${path_prefix}/ ; \
-		cp ~/output/$${path_prefix}/index.html ~/output ; \
-		cp ~/output/$${path_prefix}/404.html ~/output ; \
-	done < versions ;
+	@cd docs && npm install && npm run build
 
 view-docs: 
-		@cd docs && \
-    npm install && npm run serve
-
+	@cd docs && npm install && npm start
 
 changelog:
 	docker run --rm -v "$$(pwd)"/.git:/app/ -v "$$(pwd)/cliff.toml":/app/cliff.toml orhunp/git-cliff:latest --unreleased --tag $(tag)

RELEASES.md

@@ -3,7 +3,7 @@
 IBC-Go follows [semantic versioning](https://semver.org), but with the following deviations:
 
 - A state-machine breaking change will result in an increase of the minor version Y (x.Y.z | x > 0).
-- An API breaking change will result in an increase of the major number (X.y.z | x > 0). Please note that these changes **will be backwards compatible** (as opposed to canonical semantic versioning; read [Backwards compatibility](#backwards) for a detailed explanation).
+- An API breaking change will result in an increase of the major number (X.y.z | x > 0). Please note that these changes **will be backwards compatible** (as opposed to canonical semantic versioning; read [Backwards compatibility](#backwards-compatibility) for a detailed explanation).
 
 This is visually explained in the following decision tree:
 
@@ -13,7 +13,7 @@ This is visually explained in the following decision tree:
 
 When bumping the dependencies of [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) and [CometBFT](https://github.com/cometbft/cometbft) we will only treat patch releases as non state-machine breaking.
 
-## <a name="backwards"></a> Backwards compatibility
+## Backwards compatibility
 
 [ibc-go](https://github.com/cosmos/ibc-go) and the [IBC protocol specification](https://github.com/cosmos/ibc) maintain different versions. Furthermore, ibc-go serves several different user groups (chains, IBC app developers, relayers, IBC light client developers). Each of these groups has different expectations of what *backwards compatible* means. It simply isn't possible to categorize a change as backwards or non backwards compatible for all user groups. We are primarily interested in when our API breaks and when changes are state machine breaking (thus requiring a coordinated upgrade). This is scoping the meaning of ibc-go to that of those interacting with the code (IBC app developers, relayers, IBC light client developers), not chains using IBC to communicate (that should be encapsulated by the IBC protocol specification versioning).
 

SECURITY.md

@@ -47,30 +47,30 @@ be reported in GitHub.
 
 We require that all researchers:
 
-* Abide by this policy to disclose vulnerabilities, and avoid posting
+- Abide by this policy to disclose vulnerabilities, and avoid posting
   vulnerability information in public places, including GitHub, Discord,
   Telegram, and Twitter.
-* Make every effort to avoid privacy violations, degradation of user experience,
+- Make every effort to avoid privacy violations, degradation of user experience,
   disruption to production systems (including but not limited to the Cosmos
   Hub), and destruction of data.
-* Keep any information about vulnerabilities that you’ve discovered confidential
+- Keep any information about vulnerabilities that you’ve discovered confidential
   between yourself and the Cosmos engineering team until the issue has been
   resolved and disclosed.
-* Avoid posting personally identifiable information, privately or publicly.
+- Avoid posting personally identifiable information, privately or publicly.
 
 If you follow these guidelines when reporting an issue to us, we commit to:
 
-* Not pursue or support any legal action related to your research on this
+- Not pursue or support any legal action related to your research on this
   vulnerability.
-* Work with you to understand, resolve and ultimately disclose the issue in a
+- Work with you to understand, resolve and ultimately disclose the issue in a
   timely fashion.
 
 ### More information
 
-* See [TIMELINE.md] for an example timeline of a disclosure.
-* See [DISCLOSURE.md] to see more into the inner workings of the disclosure
+- See [TIMELINE.md] for an example timeline of a disclosure.
+- See [DISCLOSURE.md] to see more into the inner workings of the disclosure
   process.
-* See [EXAMPLES.md] for some of the examples that we are interested in for the
+- See [EXAMPLES.md] for some of the examples that we are interested in for the
   bug bounty program.
 
 [gh-private-advisory]: https://github.com/cosmos/ibc-go/security/advisories/new