Discuss Repo Organization / Branch Structure

georg-jung commented 3 years ago

I opened this to discuss how we want to organize this repo's git workflow in the future. Let's start with a brief description of the relevant topics:

git-flow

"defines a strict branching model"
- master always contains the most recent, live, production version
- develop contains the latest version of the code that is not necessarily production ready
- release/*-branches are created to stabilze a version before release (based on develop)
- hotfix/*-branches are like the release/*-ones but based on master
- further details as described by Atlassian
released versions are always created from commits on master (never from release/*)
Atlassian describes it as: This provides a robust framework for managing larger projects.

NBGV

is a small tool that automates versioning based on git commit information
- makes versioning consistent, provides a fixed framework for versioning
- implicitly links released versions to specific commits
- this has imho many more advantages, simplifies releases, supplements CI runs with additional info, etc
is quite flexible and does not dictate a strict branching model. However, it is quite common to have
- master is comparable to what develop is in git-flow
- release/v*-branches
- released versions are always created from here
- the build of every commit here could be considered to be made publicly available
- hotfixes are added here as commits
- feature/* branches as needed/if wanted. They are not touched in any way by NBGV or it's branching mindset. One might use them when creating a bigger feature/planning a PR/.... One might not use them when updating the README, introducing minimal changes etc.
is created with SemVer in mind. This fits in the above mentioned branching model. release/v1.2 would be a typical release branch. A typical version built from there could be 1.2.12 (the 12th commit after work on the 1.2 version family started). A hotfixed one would be 1.2.13. See their docs for details.

Relevant differences

release from master vs release from release/v*.
in typical NBGV setups, master is a point to start developing from, not where to start release builds from

What we currently do

Because I think NBGV provides projects with great advantages, I decided to use it.
As part of the Android Development Project I adapted git-flow for this project.
This leaves us with:
- master and develop like in git-flow.
- release/v* like in NBGV.
- Releases are actually done from release/v*.
- hotfix/* branches would be possible but never occured yet. Not sure if they ever will. One might add a commit to a release branch too.
The release process currently described in the readme isn't exactly git-flow (merges develop in master, then branches release branch).
- Because I felt this would be more reasonable I lately did - in contrast to the readme: develop on develop, branch release branch from there, merge release branch into master (thus, sticking closer to git-flow)

Problems

What we currently do is quite complicated. We want to be very beginner-friendly though. Even as a rather experienced git user it's easy to overlook some details and create git history thats not consistent with any framework/scheme/...
Looking at the most recent 25 commits, more then half of them are merge commits that don't provide any value outside the branching structure.
While I think git-flow has many great concepts and ideas, I'm not sure if strictly sticking to it (which we never really did) is a bit over the top for our project (this is not a "larger project" as per the git-flow docs, after all). I feel that contentfulCommit# < workflowCommit# is a sign of bureaucratization.
- I think strictly sticking to git-flow requires more discipline and deliberatly acting than we can assume we and future contributors have when working on this.
- After all I opened this because of #12. We can see from #12 that two things in parallel went wrong: I should have merged master into develop (earlier than today; I fixed this just some h ago). @mikimn should have started feature/contributing-guidelines from develop, not master.

IMHO

All in all I don't think managing a develop and a master in parallel provides this project with any relevant value while it complicates things quite much. Given that we probably never do hotfixing, release schedules, release stabilization etc., it's just about moving branches around without changing code. This seems error prone to me.
- I do fully agree that it makes sense to learn about git-flow as part of the Android App Project. It's a great framework to know after all. I'm just not sure if strictly sticking to it is the right thing for this real world project.
I think a slightly simplified workflow, that we can really achieve to more or less strictly stick to, would be preferable.

What I propose

Use the parts and ideas of git-flow, that work great in our use-case and simplify some of the other aspects.
Just use master (as in the NBGV section above), delete develop
Use release/v* branches, use feature/* branches
Change the readme in the following way and then simply stick to the process described there (this already fits my above proposal in all other aspects):
- - When developing new features, develop them on their feature branch ~~or on develop and then merge into master~~.
- + When developing new features, develop them on their feature/* branch. Apply minor bugfixes etc. directly on master.

georg-jung commented 3 years ago

Probably quite a read but it'd be great to know what you think about this @mikimn 😅.

mikimn commented 3 years ago

You have some good points, which I might consider at a later time to adopt. The main focus now is to give the current maintainers (students) a strict development policy which they can follow, and since GitFlow is what we are teaching, this is what should be adopted here for now. Since 2 developers are currently actively working on this, I see it as beneficial to have the extra "overhead" that the GitFlow branching model offers. This also allows me to define a unified methodology as per grading requirements, etc..

Releasing is going to be a future issue for this model which I will not worry about currently. I will consider this and leave this issue open for future discussion.

Haifa3D / haifa3d-hand-app