Docs for branching strategy

[DonLakeFlyer]

This update includes:

• A page which explains the QGC branching, tagging, versioning release strategy
• A page which explains a simple strategy for custom builds to release based on upstream QGC

[DonLakeFlyer]

@hamishwillee Could you review to make sure it make some sense. And also from the point of "Developers writing documentation" who have a hard time putting multiple sentences together.

@dakejahl Could you review with respect to the discussions we've been having. This tries to write up what we talked about.

[hamishwillee]

@DonLakeFlyer I have subedited this page. I had to infer a few things, so please check it carefully.

I think it is worth outlining what you expect for each level X, Y ,Z. It is implied but not stated that a patch is bug fixes but only very minor functionality. I would normally expect minor release for new functionality, and major release for a major change in usage paradigm OR incompatibility.

[hamishwillee]

Yes, I know "For custom builds" is implied. But it is an annoying factor of gitbook search that the context is only the text when you search".

[hamishwillee]

Do you mean repo or repro?

[hamishwillee]

I have subedited, primarily for my taste. Please check it again, but this is pretty much the same content (i.e. not as high care required as for the other doc)

[hamishwillee]

Review/subedit done. Looks good.

[DonLakeFlyer]

subedit

Uh, what's a subedit? Did you modify the pull branch itself with your changes?

[hamishwillee]

Yes. See the additional commits to this PR.

[DonLakeFlyer]

See the additional commits to this PR.

Ah, awesome. Thanks so much @hamishwillee

[DonLakeFlyer]

Comments from forum (https://discuss.px4.io/t/git-flow-recommendations-for-custom-qgroundcontrol/16127/5?u=donlakeflyer):

Thanks for the GitBranching write ups. Very helpful.
I’m still a little unclear how I layer on top of the QGC git strategy.
You write ups seem to assume I would want to develop from the latest daily build. Where I only ever want to develop from the latest stable build.

This is what I am trying to do:

I would like to create a custom version of QGC based on the latest stable release Stable_V4.0.
I understand that most of my modifications will be contained with the custom folder, but I am assuming there will be changes to core QGC outside of the custom folder. I am assuming I’m working in the same repository; perhaps I should be creating a submodule in the custom folder?
I would like to layer my Git strategy on top of the QGC strategy. This is my understanding of what this would mean:
3.1 I would create a QGC repository which points to the upstream repository (https://github.com/mavlink/qgroundcontrol) and my own remote repository.
3.2 I would develop on my local master branch (using feature branches) and push to remote/master.
3.3 I would on a regular basis do an upstream merge by pulling upstream/master. I practice, I would do this rarely; I understand that this would make the merge very difficult.
3.4 I can create pull requests on upstream by creating a feature branch off my local master, in order to contribute back to QGC. I assume good candidates for this would be changes outside of the custom folder.
3.5 I would have a local Stable_V4.0, but I would not commit to this branch. Instead I would create a local MyStable_V1.0 which would branch off of Stable_V4.0 when I’m ready to release (i.e. as late as possible) my customization; e.g. in 12 months time.
3.6 I do not develop on MyStable_V1.0, I only apply patches. All development is on my local master.
3.7 I do my custom changes to local master and pull master into MyStable_V1.0 when I’m ready to create this release. I can also pull patches from Stable_V4.0, but it would be unlikely Stable_V4.0 would receive any patches during my release cycle.
Where my confusion lies:

For now I would like to use only Stable_V4.0 commits, and not any of the commits which have since been added to upstream/master.
It looks like the latest Stable_V4.0 (v4.0.5, or even HEAD) have not yet been merged back into master. I assume it will be in the future?
So I assume what I need to do is setup my master to point to where branch Stable_V4.0 was created (hash 3cb4f124). Then pull Stable_V4.0 (tag v4.0.5 or HEAD?) into my master. Then I can continue to work on master with the Stable_V4.0 patches.
After doing #3, I would not pull from upstream/master for the foreseeable future. As I want to work from Stable_V4.0, not the latest daily build. At least until I can comfortable with QGC, and probably not until after my first release.
So my question is, how do I work from master such that it is current as of Stable_V4.0, and not include anything newer?

Or is what I’m describing what you are calling an ‘Out Of Band’ release?
If so, I understand that I would create a feature branch off of Stable_V4.0. This feature branch would in effect become my development branch (i.e. equivalent to the QGC master branch) and I would never commit to the master branch.
So for example, I would branch off Stable_V4.0 and create branch ‘develop’. I would create feature branches off ‘develop’. And when I am ready to release, I would create Stable branches off of ‘develop’.
I assume if I wish to contribute back to master, I would switch to master, create a feature branch and raise a PR, then cherry pick the changes back to ‘develop’ if the PR is accepted.

I hope what I’m asking is clear.

[DonLakeFlyer]

I'm going to take another stab at this since things are still clear as mud.

It looks like the latest Stable_V4.0 (v4.0.5, or even HEAD) have not yet been merged back into master. I assume it will be in the future?

Correct. I'm a little behind in keeping these in sync.

[matthewgkerr]

@DonLakeFlyer Thanks for adding my forum comment and your doc updates so far.

[DonLakeFlyer]

I"m going to merge and makle another pull with changes. This way it will be easier to see the new changes.

[hamishwillee]

Looks good. FWIW I'd still outline explicitly what changes go in each SemVer release number update. And perhaps address the particular case here as a "case study" at the end.

[matthewgkerr]

There is also this stack overflow question I came across while trying to understand your first bullet point on the Updating Custom Builds from QGC. Perhaps you could provide the answer to this question in the documentation?
Thanks.

[hamishwillee]

@DonLakeFlyer ^^^^ is indeed unclear.

First step states:

Create a new repository from main QGC repo. Do not clone, create a new repo, initializing it from the main QGC repo.

Do you mean "fork upstream and clone that"? If not, then probably best to spell out in git instructions.

[DonLakeFlyer]

I meant create a new blank repo and then copy the QGC repo into it which is a github option for blank repos. That said, I don't remember why not cloning was so important. @dogmaphobic Any ideas?

[dogmaphobic]

Cloning is fine. It doesn't really matter how you do it. Just make sure your "custom" folder is not included when submitting any PR against upstream QGC. Remember that "custom-example" is part of upstream QGC. Changes sent there are meant to continue showing things that can be done by "plugins" and not something specific to your new, custom code that are only relevant to you.

[DonLakeFlyer]

That said, I don't remember why not cloning was so important

I think the reason is so that you can have both a clean clone of upstream master and your own custom repo. You can't "clone" to make both of these since they will end up with the same name of "qgroundcontrol" which isn't allowed on GitHub. The other way around that is to use a single repro which you submit both custom changes to your own repo and upstream changes to QGC. But then you have to be really careful about how you do that like Gus says.

[hamishwillee]

@DonLakeFlyer In that case, can you spell out exactly how you would want it done safely in the https://dev.qgroundcontrol.com/en/custom_build/upstream_merge.html#repository-setup section?

Perhaps also add the note that "this is a good way to ensure that you don't incorrectly commit changes to the custom-example updatram.