search

OSC / ood-documentation

Documentation for Open OnDemand generated using Sphinx
https://osc.github.io/ood-documentation/latest/
MIT License
8 stars 48 forks source link

Document the branching strategy for docs #909

Open Oglopf opened 7 months ago

Oglopf commented 7 months ago

Right now I perceive the flow to look like this:

your_branch -> latest -> develop -> gh_pages

I believe the idea is to merge any changes from your_branch into the latest on the initial work. Then it looks like there's some automation to put those changes and any others desired into the develop branch. Then, when we are ready we push the develop branch changes to the gh_pages branch to publish.

I stress that I'm not sure this is the current flow but that's my impression from GitLens.

Maybe we could update the README.md to include some of this and describe the workflow to save time for people in the future and make outside contributing more simple

Oglopf commented 6 months ago

Spoke in our stand-up and it looks like we are using latest to have the current branch which is used for the docs which gh-pages then uses to generate docs.

The develop branch will be used for docs that are not published, but are being worked but will be pulled into latest at some future date.

So the flow actually should be this for a new piece of docs:

develop -> your_branch -> develop -> latest -> gh_pages

But, it sounds like we will have situations, like if you are just updating a typo maybe, where you would do:

latest -> your_branch -> latest -> gh_pages

@johrstrom Does this flow look right based on the two possible incoming change cases?

johrstrom commented 6 months ago

Yea give or take. Of course the -> are actually different mechanisms. For example -> gh-pages isn't a user action - it just happens as a part of our automation.

While we'll accept changes into develop the step develop -> latest may not happen for some time and may be misleading if it's put together in one single flow like that.

The develop branch will be used for docs that are not published,

All these branches (latest, develop and release_*) are always published once they're updated. You can see develop here - https://osc.github.io/ood-documentation/develop/ that just got updated this morning.