GitExtensionsDoc Workflow about gitextensionsdoc

[jbialobr]

5. When it is decided to do the next major release, create release/X.yy branch in code repo. In Doc repo, merge 'master' branch into 'latest' branch which will automatically update RTD. Possibly create a 'tag' in Doc repo 'master' branch identifying the major release commit.

Branch release/X.yy is created before release (a few weeks). So there should always be created release/X.yy branch in Doc repo. When new version is released then latest should be moved to release/X.yy.

[rthorp]

So, when release/X.yy is created in code repo

• create release/X.yy branch in Doc repo from 'master' branch
• when code 'package' is officially created and distributed, merge Doc repo release/X.yy branch to 'latest'

Can the Doc repo release/X.yy branch then be deleted, or does it stay 'forever'? I think tagging the master branch at the point of creating the release/X.yy branch achieves the same result as leaving a release/X.yy branch hanging around.

[jbialobr]

I think tagging the master branch at the point of creating the release/X.yy branch achieves the same result as leaving a release/X.yy branch hanging around.

There can be released minor versions from release/X.yy, so tags are neccessary.
We want to introduce long term support version (more stable see gitextensions/gitextensions#1458) like this:
Version X.Y.z is maintained until version X.(Y+2).v is released.
In example there is version 2.44.0, to which bugifxes (2.44.1, 2.44.2, ...) are released until 2.46 is released.
Then it stops being long term and 2.45 starts being long term version.

[rthorp]

Ok, updated workflow:

1. the 'master' and 'latest' branches always exist. The official RTD doco is always built from 'latest' branch.
2. updates to documentation for the currently released version of software are first merged to 'latest', then 'master'.
3. changes to documentation for upcoming releases are handled as follows:
   a) if developer is ok with updating doco for their feature, create same feature/XXX branch in Doc repo (branching off from 'master') and update the documentation.
   b) if developer does not create their own doco, then once feature is completed (but not yet merged into code repo 'master') an Issue is raised in the Doc repo that details what the feature implements (e.g. screen changes, logic changes) so somebody can update the documentation to reflect the feature. A feature/XXX branch is created in the Doc repo (i.e. same name as in code repo).
4. Once both code and documentation are complete, the feature/XXX branches can both be merged into their respective repos 'master' branches and deleted.
5. When it is decided to do the next major release, create release/X.yy branch in Doc repo from the 'master' branch. Merge new release/X.yy branch into 'latest' branch as well to automatically update RTD.
6. When long term support/minor versions implemented, merge any feature/XXX bug fix branches created into any applicable release/X.yy branches and also into 'master' and 'latest'. Create tag in release/X.yy branch identifying commit as release/X.yy.z

I apologise if you think I am going into too much detail, but I think if people have a clear set of instructions on how to do something, then when it comes time to do it, you don't need to rely on your memory! I would like to add some sort of HOWTO document to the Doc repo as well so all these things are documented and can be altered as different/better ways of doing things are found.

[jbialobr]

I apologise if you think I am going into too much detail ...

Oh, it is very good. From my experience I know that everything that wasn't said(written) it just wasn't said and can be freely interpreted. Moreover there is 99% of chance that it will be interpreted in a different way from the way you expected/meant.

There is a wiki page in code repo, I think it would be a good place either for workflow description.

[rthorp]

Moreover there is 99% of chance that it will be interpreted in a different way from the way you expected/meant.

lol - you are quite correct!

There is a wiki page in code repo, I think it would be a good place either for workflow description.

Just had a look at the Wiki. I agree that would be a good place to put workflow info. Can have separate sections for Developers/the repo admins, etc.

I will put it on my list of things to do :)

[martinqt]

The workflow would also be nice in the readme and in a contributing file (and don't remember the exact name for github to put a link when submitting PR).

[rthorp]

I am currently creating Wiki pages for this workflow (on my own fork at the moment). Can somebody answer the following questions:

• should emailed patches be accepted for doco updates? If so, to what email address?
• I notice that the main code repo has a GitExtensionsDoc submodule. Does this affect how developers modify documentation? I am not familiar with submodules so if a developer has forked and cloned the code repo, do they also need to do a separate fork and clone of the doco repo to modify documentation? Or can they use the submodule in the code repo to, for example, branch off from the 'latest' branch in the doco and make changes?

[jbialobr]

should emailed patches be accepted for doco updates? If so, to what email address

No, it should be done by creating a pull request.

do they also need to do a separate fork and clone of the doco repo to modify documentation?

Yes.

[rthorp]

I have created some Wiki documentation - please review https://github.com/rthorp/GitExtensionsDoc/wiki.

These are the Wiki pages i would like to put on the Wiki in the main code repo.

@martinqt - I would rather workflow is in only one place - having separate copies in different places is too hard to maintain - you have to update multiple copies. I think the Wiki should be mentioned in the README.MD files on both the code and doco repositories.

[jbialobr]

Cool. I like it. I did small changes about the necessity of creating a PR to merge the latest into the master. This is a maintainer job to do such a merge. I think after you review/correct changes I did, you can put it on the Wiki in main code repo. If you could add information in Coding guide pointing to https://github.com/rthorp/GitExtensionsDoc/wiki/Future-Release about updating documentation or raisng an issue ?

[rthorp]

Your changes are fine. I have modified the Current Release page a little to state more clearly that somebody can raise a new issue or pick up an existing one to work on - and also to say they are working on it.

Not sure what you mean by updating the Coding Guide on the main repo? My intention was to actually copy all of the pages I have created into the Wiki on the main repo, then delete them from my fork. I only put them on my fork so I could create them and you could review them.

If however you just want a link on the main repo Wiki page to the Wiki on my fork, that is okay as well.

[jbialobr]

My intention was to actually copy all of the pages I have created into the Wiki on the main repo, then delete them from my fork. I only put them on my fork so I could create them and you could review them.

Yes, I understand. I thought that Updating the Documentation will be a stand alone section below Coding guide
but it is also fine to do it as a point in Coding guide like this

[rthorp]

I see. As the documentation is separate from coding, I was just going to put the Updating the Documentation heading/text below the Coding Guide section so you would have 2 separate sections. I will do it this way for now. Have a look and see what you think, then you can change if needed.

(Give me 10 mins to do it).

[rthorp]

Ok, added to code repo Wiki.

[rthorp]

Do you want to add a link to the home page of the Wiki in the code repo README.markdown file? Under the Links section?

[jbialobr]

It would be good as for now it is quite hidden.

[jbialobr]

I would add a bullet point to Coding guide to tell about necessity of updating doc or raising an issue, because it is not clear at the first glance.
You have go to Current Release or Future Release to get know about it.

[rthorp]

Ok. Added a bullet point, but cannot get the same page link to work i.e. my sentence in the Wiki is:

(see [Updating the Documentation](#updating-the-documentation)

But the Wiki translates that link into the following URL:

https://github.com/gitextensions/gitextensions/wiki#wiki-updating-the-documentation

It puts the text wiki- in front of updating-the-documentation.

The actual link to the section is

https://github.com/gitextensions/gitextensions/wiki#updating-the-documentation

i.e. without the wiki-. I can't seem to fix this - any ideas?

[jbialobr]

Maybe write sth like this: (see Update for Current Release or Update for Future Release depending on what you do)

[rthorp]

Put in the full link to the section on the page - works now. :)

[jbialobr]

Thanks.

[rthorp]

I see you have added the Wiki link into the README on the code repo. I have done the same on the doco repo. Will close this issue now as everything has been done. Thanks @jbialobr .

[jbialobr]

I would like to write workflow for code repo. Could I send it to you for a review when I finish?

[rthorp]

Sure, I'd be happy to review it.