[Issue #1820] Syncs ADRs with wiki

[widal001]

Summary

Moves documentation/decisions/ to documentation/wiki/decisions/ so that future ADRs will show up in both GitBook and in the repository.

Fixes #1820

Time to review: 5 mins

Changes proposed

What was added, updated, or removed in this PR.

• Moves documentation/decisions/ to documentation/wiki/decisions/
• Adds a adr/README.md file so that wiki users can browse all of the ADRs
• Renames infra/index.md to infra/README.md to do the same for Infra ADRs
• Updates SUMMARY.md so that the newly synced files will appear in the wiki UI
• Adds ci-wiki-links.yml to check that all files in documentation/wiki/ are in SUMMARY.md

Context for reviewers

Testing instructions, background context, more in-depth details of the implementation, and anything else you'd like to call out or ask reviewers. Explain how the changes were verified.

Note: If ADRs are introduced via a PR in GitHub, they also need to be added to SUMMARY.md in order to appear in the wiki. This PR also adds a CI check that will run when the documentation/wiki/ directory is updated in a PR and it will check that all markdown files are linked in SUMMARY.md

Here's an example of what a failure looks like

Additional information

Screenshots, GIF demos, code examples or output to help show the changes working as expected.

To see what this will look like in the wiki, you can check out this preview it should look like this:

[sumiat]

PR looks good to me!
Just to make sure, for the description you stated below, you are adding it to the wiki and it will remain in github? we're not removing it from github?:

Moves documentation/decisions/ to documentation/wiki/decisions/

I think we just need a couple follow up things to make sure we're aligned on the process. These do not block approval of the PR:

Note: Future ADRs should probably default to being drafted in GitBook. If ADRs are introduced via a PR in GitHub, they also need to be added to SUMMARY.md in order to appear in the wiki.

• That's easy to miss so we'll want to make it clear to the team that we're creating the ADRs in GitBook now.
• Could you remind me @widal001 how often we're syncing the wiki to github?

[acouch]

Didn't know this was possible! Very cool.

If ADRs are introduced via a PR in GitHub, they also need to be added to SUMMARY.md in order to appear in the wiki.

I would like to check w/ the team about this. The PR process has worked for us so far. We could use adrlog to generate the index so it happens automatically.

[widal001]

@sumiat @acouch Wanted to update y'all on some changes I made to this PR and answer some of the questions above:

Updates

• I added a new CI check that runs when a PR is opened that changes the documentation/wiki/ directory. It will fail if any of the markdown files that are added to this wiki are missing from the SUMMARY.md which is useful outside of just the new ADR workflow since it will also allow us to lint PRs opened by open source contributors that touch the wiki.
• Here's an example of a failure which lists the missing file and the source commit in which I removed that file to trigger the failure
• Now that we have all of the ADRs added, folks will only need to add individual ADRs to the SUMMARY.md file and this check will fail if they forget to do that

Other notes and responses

Could you remind me @widal001 how often we're syncing the wiki to github?

The wiki and GitHub get synced every time a new GitBook change request is merged and every time a GitHub PR is merged that contains code which modifies documentation/wiki/

I would like to check w/ the team about this. The PR process has worked for us so far. We could use adrlog to generate the index so it happens automatically.

Even if we use adrlog to generate the index, we still need to add new files to documentation/wiki/SUMMARY.md for GitBook to pick them up. The CI check that I mentioned above will fail when this doesn't happen so we should be able to catch it in the PR, but we can also explore options for automating the process of inserting new links as well down the line if manually adding them when a new ADR is created becomes burdensome.

[sumiat]

Thanks for the updates, Billy! LGTM. Not sure if Aaron has more questions!

[sarahknoppA6]

Wow, this looks great! These changes will be really helpful. Thank you very much for putting them together and for the thorough documentation around them :)

[sumiat]

Approved!