Development Documentation on Git/GitHub

[TimothyWillard]

Describe your changes.

This pull request adds documentation on development, in particular on git/GitHub usage. It doesn't include a visual yet (although I think that would be super helpful), because this great visual created by @pearsonca doesn't contain hot fixes yet and also have to figure out the best way to include this image. I believe the documentation accurately reflects where we have landed but if there are issues please let me know.

What does your pull request address? Tag relevant issues.

This pull request addresses the documentation portion of GH-369.

Tag relevant team members.

@alsnhll @emprzy @fang19911030 @jcblemai @MacdonaldJoshuaCaleb @pearsonca @saraloo @shauntruelove @twallema

[pearsonca]

Everything that's addressed here works for me.

However, we also need to address how gitbook integrates with this.

I recommend:

• we designate gitbook maintainer team
• dev changes should also have whatever documentation/... changes corresponding to feature changes; these do not propagate to gitbook until release stage (see below), but should try to get gitbook team comments when merging features
• bugfixes to main that also entail documentation/... changes should PR to gitbook; gitbook team has responsibility to deal with any merge issues (n.b. bugfixes always push to dev irrespective of gitbook changes, for which dev folks are responsible for rebase/merge issues)
• changes via gitbook api / or directly to gitbook branch would be merged to main during the release stage
• during release: should be able to apply dev directly to main (dev folks have responsibility for merge issues). then apply gitbook revs (gitbook maintainers responsible for merge issues, ideally this should be a straightforward rebase).
• once release is resolved, both dev and gitbook should point to new main release commit

[saraloo]

Thanks, the documentation is super clear and helpful instructions from an ops perspective. 👍

[TimothyWillard]

I made some minor edits to clarify how documentation works. However, I did not make mention of a "GitBook maintainer team". I think that would require some discussion outside of this PR to come to a consensus.

[anjalika-nande]

These instructions are very clear to me, thanks!

[alsnhll]

I can't find instructions anywhere here on how to logistically integrate changes to flepi code with changes to the Gitbook documentation during the development process. How did you do it here? When I go on Gitbook I do not see any option to make changes in a new branch, ie the dev branch. How did you do it here? I know you could just edit the raw files in any text editor but that's not ideal - the whole point of Gitbook is it's easy interactive editing and you get to see in real time that it's formatted as desired. We should add some documentation to clarify this part of the process?

[TimothyWillard]

I know you could just edit the raw files in any text editor but that's not ideal - the whole point of Gitbook is it's easy interactive editing and you get to see in real time that it's formatted as desired. We should add some documentation to clarify this part of the process?

The workflow as described here does not accommodate using the GitBook web editor for documenting changes to flepiMoP made in development. From what I understand GitBook tracks the documentation in it's own repository so you can not use the GUI to edit changes to branches on GitHub (besides the documentation-gitbook branch which contains the live GitBook). You can create change request in the app and request reviews from there, however I have a preference for the editing of the raw files so we don't have to jump between two apps and can keep the documentation in sync in the dev branch with the features being added. I'm happy to add notes on how to work with the GitBook web app in this workflow if we agree on a best way to do it, it just doesn't fit well right now.