Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Untrack and auto-generate params.md on docusaurus_start #942

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

bryanchriswhite
Copy link
Contributor

@bryanchriswhite bryanchriswhite commented Nov 21, 2024

Summary

  • Remove docusaurus/docs/protocol/governance/params.md from version control because it is [generated automatically on deployment], which allows the published version to get out of sync with what's in git.
  • Add docusaurus/docs/protocol/governance/params.md to .gitignore so that it ignored going forward.
  • Add docs_update_gov_params_page as a dependency to the docusaurus_start so that params.md is available when building and serving docusaurus locally.

Issue

#933 (review)

Type of change

Select one or more from the following:

Testing

  • Documentation: make docusaurus_start; only needed if you make doc changes
  • Unit Tests: make go_develop_and_test
  • LocalNet E2E Tests: make test_e2e
  • DevNet E2E Tests: Add the devnet-test-e2e label to the PR.

Sanity Checklist

  • I have tested my changes using the available tooling
  • I have commented my code
  • I have performed a self-review of my own code; both comments & source code
  • I create and reference any new tickets, if applicable
  • I have left TODOs throughout the codebase, if applicable

@bryanchriswhite bryanchriswhite added documentation Improvements or additions to documentation governance Governance related changes code health Cleans up some code labels Nov 21, 2024
@bryanchriswhite bryanchriswhite self-assigned this Nov 21, 2024
@bryanchriswhite bryanchriswhite marked this pull request as draft November 21, 2024 08:18
@bryanchriswhite bryanchriswhite marked this pull request as ready for review November 21, 2024 08:19
Copy link
Member

@Olshansk Olshansk left a comment

Choose a reason for hiding this comment

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

What if we keep it in version control but also build it in docusarus_start?

I'd like to maintain both to avoid "ephemeral docs"

@bryanchriswhite
Copy link
Contributor Author

What if we keep it in version control but also build it in docusarus_start?

I'd like to maintain both to avoid "ephemeral docs"

If we do that, there would still be a possibility that version control gets out of sync with what's deployed unless we also add a CI check which make docs_update_gov_params_page (or docusaurus_start) and fails if any markdown files change in the docusaurus directory.

@Olshansk
Copy link
Member

@bryanchriswhite

  • Things I feel strongly about: not having this README as part of version control. This impacts searchability, indexing, etc...
  • Things I feel less strongly about: things being out of sync.
  • Things I do not think are a high priority but can be done in the future: automation to ensure things don't get ouf of sync.

Wdyt of just adding a TODO to add the check you mentioned (it's ULTRA LOW priority) and closing this PR w/o merging?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
code health Cleans up some code documentation Improvements or additions to documentation governance Governance related changes
Projects
Status: 👀 In review
Development

Successfully merging this pull request may close these issues.

2 participants