Skip to content

docs: Update all docs to prepare for v0.37#9243

Merged
thanethomson merged 36 commits intomainfrom
thane/9096-tmdocs
Aug 19, 2022
Merged

docs: Update all docs to prepare for v0.37#9243
thanethomson merged 36 commits intomainfrom
thane/9096-tmdocs

Conversation

@thanethomson
Copy link
Contributor

@thanethomson thanethomson commented Aug 13, 2022 •
edited
Loading

Partially addresses #9096.

In addition to updating all links from master to main in the docs folder, this PR:

  • Removes the v0.35.x docs build
  • Adds a convenience Makefile target to serve the docs locally (make serve-docs)
  • Attempts to resolve OpenAPI link on docs.tendermint.com is static #7908
  • Updates some communication-oriented links (e.g. pointing people to discussions)
  • Updates most links to the old spec repo to instead point to this repo (I say "most" because many links have specific commit hashes, or are links to issues in the spec repo, so it's probably best to leave them as-is)

In order for the documentation to build correctly, we first need to merge the following PRs before we merge this one:

Important files to review in this PR:

PR checklist

  • Tests written/updated, or no tests needed
  • CHANGELOG_PENDING.md updated, or no changelog entry needed
  • Updated relevant documentation (docs/) and code comments, or no
    documentation updates needed

@thanethomson thanethomson changed the title docs: Update docs.tendermint.com build to prepare for v0.37 docs: Update all docs to prepare for v0.37 Aug 13, 2022
This was referenced Aug 13, 2022
Merged
Merged
Merged
@thanethomson thanethomson marked this pull request as ready for review August 13, 2022 21:34
@thanethomson thanethomson requested a review from ebuchman as a code owner August 13, 2022 21:34
@thanethomson thanethomson requested review from a team August 13, 2022 21:34
@thanethomson thanethomson marked this pull request as draft August 13, 2022 21:38
cmwaters
cmwaters approved these changes Aug 15, 2022
View reviewed changes
Copy link
Contributor

@cmwaters cmwaters left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

I think in some cases we need to stop using main and use a fixed tag or commit so it doesn't change and become broken

@tychoish
Copy link
Contributor

tychoish commented Aug 15, 2022

Why is this PR marked draft but the other two aren't?

I sort of feel like it would be more clear to do the s/master/main and then back port that and then do any other changes to the legacy branches, but this works two. I don't have a high degree of confidence in the docs build system, but I think that's fine as long as we watch/test each deploy and are ready to do reverts as needed.

@thanethomson
Copy link
Contributor Author

thanethomson commented Aug 15, 2022

Why is this PR marked draft but the other two aren't?

As per the PR description, the other two PRs need to be merged first before this one. The way the docs build says that each of the other two branches are checked out and built as well whenever we push to main. Merging this first would mean we'd need another incidental update to the docs in main to trigger the docs deployment workflow.

@cason
Copy link

cason commented Aug 16, 2022

What is the policy to rename master -> main or master -> latest?

@thanethomson thanethomson force-pushed the thane/9096-tmdocs branch 2 times, most recently from 4cd8930 to 062dd36 Compare August 17, 2022 00:25
cmwaters
cmwaters reviewed Aug 17, 2022
View reviewed changes
@thanethomson thanethomson marked this pull request as ready for review August 18, 2022 01:17
@thanethomson
Copy link
Contributor Author

thanethomson commented Aug 18, 2022

What is the policy to rename master -> main or master -> latest?

After much back and forth, I decided to just go from master -> main. I considered a rename from master -> unstable, but it's probably less confusing overall to keep it main.

If we went with latest it wouldn't be built from main, it would be built from our latest release branch (i.e. "latest stable"). We can still opt to enable this if we really want (it's literally a one-line change in the docs/versions file). I'm still skeptical of the value of this because then we'd need to keep our docs/.vuepress/redirects file up-to-date. Every time there's any structural change to any document (docs site page, specification, ADR, RFC, etc.) we'd need to update that redirects file.

@thanethomson thanethomson mentioned this pull request Aug 18, 2022
Closed
39 tasks
tychoish
tychoish approved these changes Aug 19, 2022
View reviewed changes
docs/DOCS_README.md
the `master` branch. Any updates to files in this directory
on those branches will automatically trigger a website deployment. Under the hood,
the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo.
There is a [GitHub Action](../.github/workflows/docs-deployment.yml) that is
Copy link
Contributor

@tychoish tychoish Aug 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe if this is rendered in the docs site it will be wrong, but it's fine if that's never the case. It's always safe to do absolute/full URL links

Copy link
Contributor Author

@thanethomson thanethomson Aug 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is rendered, but it's not actively linked to from anywhere in the docs. The GitHub version of this doc is linked to from here.

@thanethomson
Update docs references from master to main
b100aca 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update DOCS_README to reflect current reality
021f662 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update vuepress config with current versions and updated discussions …
60c4a20 
…link

Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update generated docs versions
f8e27ce 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update docs build to use temp folder instead of home
4e5e312 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Document build-docs Makefile target
6b7a1b5 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Add serve-docs Makefile target to serve local build of docs
d2e4f55 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update OpenAPI references from master to main
93fcca2 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update CHANGELOG references from master to main
435b4ce 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update Docker readme references from master to main
91ac9c2 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update UPGRADING references from master to main
d409aa2 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update package-specific documentation references from master to main
8ad3a6b 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update spec references from master to main
f2e6787 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update all code comment references to docs site from master to main
a2c8d1e 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Build v0.34.x as "latest"
6684438 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Explicitly mark v0.34 docs as latest in version selector
51704d8 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update all links from docs.tendermint.com/main to docs.tendermint.com…
c3f9b78 
…/latest

Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
ci: Redeploy docs on pushes to v0.34.x
730a1c2 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Temporarily copy spec directory into docs while building
1bed259 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Add nav link to main and clearly mark as unstable
f28da6a 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Revert to only publishing docs in nav for v0.34 and v0.33 with no latest
0caed6a 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Link to docs.tendermint.com/v0.34 from RFCs
c55b3a9 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Rather just use main for all docs.tendermint.com references on main b…
fb2a814 
…ranch

Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Rename GitHub tree links from master to main
884bd6c 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update link for ABCI Rust client
283b44e 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update github links from master to main
6789fe5 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Update badges in root readme
5c13a96 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Remove codecov badge since we do not use it any more
dcacaa3 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Remove Java and Kotlin tutorials
37eb321 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Remove specs from docs build
76dacc4 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Migrate spec links to GitHub repo from docs site
c5914d0 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Remove references to non-existent PEX reactor spec
38f4dd8 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson
Fix linting badge in README
8ce306c 
Signed-off-by: Thane Thomson <connect@thanethomson.com>
@thanethomson thanethomson merged commit daaf5d6 into main Aug 19, 2022
@thanethomson thanethomson deleted the thane/9096-tmdocs branch August 19, 2022 17:18
@thanethomson thanethomson mentioned this pull request Dec 23, 2022
Closed
38 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ebuchman ebuchman Awaiting requested review from ebuchman

2 more reviewers

@cmwaters cmwaters cmwaters approved these changes

@tychoish tychoish tychoish approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

Tendermint
Status: Done/Merged

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

OpenAPI link on docs.tendermint.com is static

4 participants

@thanethomson @tychoish @cason @cmwaters