Docs-website: Support bulk updates to documentation in private forks

[jpvajda]

When working on major documentation changes for new releases New Relic doesn't always want those to be available to public view in the form of open PRs or draft PRS, therefore we need to come up with a way to:

1. Support many contributors working on docs contributions simultaneously in local private forks of the site repo.
2. Figure out a seamless way to allow those changes to merged back into the public site repo when ready to release.
3. Reduce merge conflicts of those working on different private forks to allow a quick an easy merge into the public site repo.

Example Use Cases

• Multiple writers are making changes to dozens or hundreds of docs ahead of a large launch. They need to stay in sync with each other, review one anothers' work, and easily deploy on release day.

• A writer is working on several sets of inter-related changes to a doc ahead of a release. They need to share those changes with a PM to get their review

References

https://medium.com/@bilalbayasut/github-how-to-make-a-fork-of-public-repository-private-6ee8cacaf9d3

Acceptance Criteria

• [x] Define the git workflow that will solve these challenges.
• [X] Define the branching strategy to facilitate the new workflow.
• [ ] provide documentation to the Docs Team in a new contributing guide section called Working on Bulk edits similar to this section
• [ ] Review this process with a few Docs Team members for real time feedback @austin-schaefer will act a point person, so a session can be scheduled to review the process and he'll invite people.

[jpvajda]

@austin-schaefer feel free to add context or use cases.

[austin-schaefer]

Notes from Slack chat on this:

Isn't this the same use case as the preview/private private docs site?

@austin-schaefer : It's pretty different—this is about working on dozens/hundreds of edits to different pages in preparation for a release.

Can we just handle this with local branches?

@austin-schaefer :

Local-only isn't really an option unfortunately. There's two main issues:

• Bus factor. If a writer leaves, goes on vacation, wins the lottery, etc etc we need other writers to be able to pick up the work. It's also common for writers to "swarm" on large projects like this.
• Collaboration and review. We need writers and stakeholders to be able to review changes before they go live.

Previews

@jerelmiller : Do you need PR previews or anything like that? I just mean not available at a published URL. Since its git, you'd still be able to checkout someones branch, and yarn start to see the changes. otherwise, the regular GitHub workflow would remain the same

@austin-schaefer : Ye-es, I think that would work but I probably need to chew on this longer.

@jerelmiller : That sounds good. We could technically spin up a 3rd Amplify instance and connect it to the private fork, but would be one more thing to manage

[austin-schaefer]

Example use cases:

• Multiple writers are making changes to dozens or hundreds of docs ahead of a large launch. They need to stay in sync with each other, review one anothers' work, and easily deploy on release day.
• A writer is working on several sets of inter-related changes to a doc ahead of a release. They need to share those changes with a PM to get their review.

[jpvajda]

@zstix I'm wondering if this is small enough if we could just knock it out in Sprint 1, and get it off our list of things to do. Thoughts. 🤔

[zstix]

We have some _rough_ steps for how to do this via a fork workflow here. We can work to clean up that documentation and then check with the writers to see if this meets our needs.

[jpvajda]

Our first non-engineering approach will be to better articulate how this can be done using the existing GIT workflow for private edits. We'll then evaluate how that is going for a while and consider other contributor needs that aren't being met using a standard GIT workflow that exist for developers who do work this same way on projects. @austin-schaefer .

We hope we can solve this with little to no engineering, but we are open to evaluating this further in the future.

[jpvajda]

@nr-kkenney chatted in depth about this ticket and:

1. public repo forks can't be change to private. so that's not an option.
2. To duplicate a repository without forking it, you can run a special clone command, then mirror-push to the new repository Here is a How to. but this then puts a lot of responsibility onto the Docs Writer to manage this repo and then give others access to it. If a user hosts a duplicate repo on a free github account they are limited to 1 owner + 3 contributors
3. Finally, when consider if we can do this on private docs and just put something in place to sync Public Docs to Private docs (thus: creating a replica of Public Docs) some considers have to made for how this would add to our teams responsibility to manage this Private Site as a full-fledged Gatsby site.
4. Also if we did replicate Public Docs to Private docs on some interval, we have the need to have the private docs functionality still be available. Which allows us to send a customer a beta or preview doc. It's possible if we do replicate the site that this wouldn't be a problem as we'd have all the core functionality available to a user previewing abeta or preview doc.
5. A share working branch approach would only work on a repo, so if that can't be public docs, then it would have to be a duplicate hosted somewhere else. See the above note about that challenge

[zstix]

Possible Options

• Use the private docs repository as-is
• Use the private docs repository with the addition of the side nav (extra engineering effort)
• Use the fork / remote workflow outlined in CONTRIBUTING.md

[austin-schaefer]

Thanks for the context @zstix @jpvajda . Can we set up a call to walk through these options in greater detail? As I mentioned to @jpvajda the other day in Slack, if you can set up a call w/ me and then I can add other writers as-needed.

[jpvajda]

We have an internal doc under review now... once we confirm our approach will work, we can document it in in the Contributor guide.

[nr-kkenney]

pr merged. closing.

future / related work is captured in #1685, #1686.