Repository branching and tagging, versioning

[ThomDietrich]

Hello @marvinroger,

Somewhere in comments we already discussed that branching in this repository should be addressed. I want to restart that discussion. Here's my first suggestion, which is open for discussion:

1. Introduce a strict versioning system - Homie is a convention to be followed by other development projects. It is hence important to add unambiguous version numbers for every convention revision. A developer needs to be able to state "The app conforms with the Homie convention v2.1.3". I suggest to implement semantic versioning: http://semver.org (should be a perfect fit)

2. Work in the main branch only - Currently there is an outdated master branch, an unclear v2.0 branch and a redesign branch. That is neither intuitive nor visible to a reader. As the convention is steadily evolving, we should present the latest revision to the interested developer/user. (With the option to switch to other versions, see 5)

3. Use tags to mark versions - A homie version is a fixed state of the document, hence tags are perfectly fine for the job. (Other branching models suggest branches in order to allow e.g. hotfixes)

4. Version every commit - Almost every commit will change details of the Homie convention, it is therefore needed to increment the version number as the MAJOR.MINOR.PATCH system of semver suggests. (Exceptions are of course commits with language changes only)

5. GitHub releases for stable tags - GitHub offers the releases tab to publish versions and add a release note. That should be used to announce and document the stable and noteworthy releases (e.g. v1.5.0, v2.0.0, v2.1.0)

6. Link the "Tags" tab in the first part of the convention - For readers to quickly find all available homie versions, the tags tab should be highlighted in the first part of the convention document.

Everyone, please add your comments, criticism and feedback!
Best! Thomas 🍻

[marvinroger]

Hi @ThomDietrich
Thanks for that! Actually, this was already planned (we do exactly all of that on https://github.com/marvinroger/homie-esp8266). I wanted to "clean everything" as soon as we all agreed about the v2.1.0, which will be the last release that breaks semver (the v2.0.0 is not really backward compatible, but I'd say this is fine as the v2.0.0 was never released officially).

The only thing I did not think about was the "Tags" tab. Great idea! 👍

[marvinroger]

e0e3bad ✨

[ThomDietrich]

@marvinroger just a thought before it's too late. After all recent additions and changes I wonder if 2.1.0 is the correct version to choose. How about 3.0.0 or 2.5.0?

Btw I believe that not having any versioning right now (and for the last couple of weeks) is not good...

[marvinroger]

I agree that v3.0.0 would be semver-compliant. I don't know, because the v2 was actually never released. But yes, the versioning was chaotic. Let's follow semver and go for v3. 😈

We'll have it ready very soon, that'll be a thing of the past. 😉

[bodiroga]

Hi @marvinroger!

What's left for the release of the official Homie 3.0 version? All PR's are merged and all big issues are closed, what else needs to be done?

Many thanks for all your hard work! 👍

[ThomDietrich]

@marvinroger I really think the current repo situation is all other than ideal. We should do something about that... You can always start by creating a beta release or similar... Everything is better than the current state.

[timpur]

Added some tags and releases, getting close :)

[ThomDietrich]

@timpur thanks for pushing development forward. I'd suggest to do a few things right away, in order to finally reach a production ready and extendable state:

• change the version of the redesign branch as it is right now to v3.0. (This version step was discussed above and your ideas over in Homie Convention v3.0 (redesign) #61 can just as well be added with 3.1, 3.5 or 4.0.)

• Merge redesign into master, delete all other branches

• Add and clean up tags

... So basically enforce everything I've noted down in the first message here 😃 What do you think?

[ThomDietrich]

@timpur did you miss the mentioning?

What do you think? If you are not disinclined, I'd go and apply the changes tomorrow.

[timpur]

Yes, just stretched for time atm ....

[ThomDietrich]

@timpur @marvinroger
I might have overestimated my free time back in the last comment :D
Just so we are all on track: Do we want to go forth with the plan to mark version 3.0 now, then address all existing issues? A simple 👍 would be enough to show your approval. 😉 I'll do the needed work then.

[timpur]

What are some of the big issues atm, tbh not following them all ... but yest i think were ready for 3.0

[marvinroger]

Definitely! Sorry for my tiny presence here, I have been preparing my internship defense, which is tomorrow! 😊 Le lun. 19 févr. 2018 à 13:56, Thomas Dietrich <notifications@github.com> a écrit :

…

@timpur <https://github.com/timpur> @marvinroger <https://github.com/marvinroger> I might have overestimated my free time back in the last comment :D Just so we are all on track: Do we want to go forth with the plan to mark version 3.0 now, then address all existing issues? A simple 👍 would be enough to show your approval. 😉 I'll do the needed work then. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#46 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA8eNYO7LWvql-JmbkTdi60Ec3Vd55DZks5tWW-KgaJpZM4PjPFh> .

[ThomDietrich]

@marvinroger Good luck!

[timpur]

@ThomDietrich, Do what you can and ill help when i can :)

Thank for contributing.

[bodiroga]

Hope that everything went fine @marvinroger!

Thanks for all your work guys!

[timpur]

Question, how do you guys prefer to do implementation versioning? eg ESP implementation? Should it align with Homie version? or independent and just state what version of homie its using?

[ingoogni]

Yes, IMHO it should be clear what versions of both match

[timpur]

yes but what :P ?

[ingoogni]

H3.0ESP23.04

[timpur]

Damn

[timpur]

Could be:
c = Homie Convention
i = Homie Implmentaton version
c.c.i.i
so for Homie ESP currently that would look like 2.0.2.0 think @nerdfirefighter said this.
but not sure about it, i think they should be separate, just need to document these version better, and display them more !!!

[timpur]

@marvinroger need you to remove v2 branch, and set master as default. I have merged and cleaned up branch v2 so you can remove.

Master sits at v2.0 now and is ready for redesign branch (3.0) we will work on redesign and master will reflect most recent release always.

We now need to get 3.0 ready for release.

[ThomDietrich]

@timpur I have to apologize. I ran into some unforeseen problems in my personal endeavors and didn't get around to continue here. Thanks for taking matters into your hands.

One thought I want to mention: You've changed "2.1.0" to "3.0" but it should read "3.0.0". Is this a mistake? Please compare: http://semver.org/

[timpur]

Didn't know what existed .... Good to know. My mistake, will fix

[euphi]

Yes, but what's your problem with a v2.0.x branch? There is no need to merge it back.
That's why branches were invented... :-)

[ThomDietrich]

Exactly. You will see that everything falls into place once you start working on it.
Maybe this way of thought helps: In the end not your branch is the important artifact, your tag is. You will branch off of the v2.0.0 tag, add your changes in one or multiple commits, then create a tag "v2.0.1".
This tag is the important thing and is what will be available to users later. At this point no one cares on which branch it is based. The branch will not be merged into master or anywhere else.

@euphi regarding the branch name. After consideration, I wonder if we should prefer patch-v2.0.x over release-v2.0.x? (details...)

[timpur]

Okay, if you dont thing git will garbage collect the unmerged commits in a deleted branch with a tag then sure. Im all in.

Should we just squash and merge PRs ?

[euphi]

@timpur
Who wants to deleted the branch?
There is absolutely no reason to do this.

[euphi]

@ThomDietrich
I wanted to avoid the "hotfix-v2.0.x" branch name. As the "release-v2.0.x" name is proposed in the "git flow"-branching model, but we don't follow this model*, I'm fine with another name.

• in that model, the release-branch is created for developing the release and then merged back into master for the release. The git flow model does not offer a solution how to maintain old releases. (Not even for hotfix?!).

[ThomDietrich]

@marvinroger the master branch is protected and I can't push destructive changes. (Good so far! 😉)
However it would be meaningful to remove the latest commit on master to end up with a clean commit graph. Could you please do the following? Thanks!

git checkout master
git pull
git reset --hard 3bcbb01ef31205a5c2a19522fc9b6dd892d1c274
git merge --ff-only origin/redesign
git push

@euphi ultimately I've no strong feeling to one or the other. In another project I'm involved in we do something similar with patch-v2.0.x but yes, let's settle with your release-v2.0.x
(I'm aware it is used differently in Git Flow, who cares.)

[marvinroger]

@ThomDietrich done 😉

[timpur]

Wait I thought the whole point of this was to only have one branch master and use feature branches only to make changed but they eventually get merged and deleted ? So won't 2.0.1 be the same. I'll tag it and relase it and then delete the branch ?

[euphi]

No, that's just not possible.
If you want to maintain a old release, you must have a branch for it.

The github flow and git flow models don't consider maintaining an old release, so we can't use them.

• So develop in master or feature branches.
• Release (tag) on master
• create release branches only to develop and tag a maintenance version of an old release

[marvinroger]

Are we ready to move to @homieiot? No immediate concerns about that?

I am just wondering, should we name it homieiot/homie or homieiot/convention? One thing, I'd like to create a website that would render the convention markdown, and having it as https://homieiot.github.io/convention sounds cleaner than https://homieiot.github.io/homie

[marvinroger]

Oh and yes @ThomDietrich, I remember that we already discussed about moving the convention to its own org. I was then looking for a job, and my GitHub weighted more than my CV. I am now in a comfortable position, so now that my career is "bootstrapped", I have no problem moving the convention. 😉

[euphi]

I also prefer "convention".

[euphi]

Regarding moving to homieiot? Should we fork the repository to keep history or should we create a new Repo?

For creating a website, the directory structure will change, so maybe a new repo is better?

So before moving the contents, we should clarify:

• Which site generator shall be used?
• When and how do we move content (the actual convention?)

[ThomDietrich]

@marvinroger great. looks good now.

@euphi we don't have to worry about history. Moving a repo just means it will be shifted into another namespace. Btw. GitHub will auto-redirect the current repo URL to the new one so that links and users will still find their way.

@marvinroger we are in total sync :D I was also thinking about https://homieiot.github.io/convention 😉
Let's move. I'll add my PR after the move.
Regarding the homepage: Fine with me.

[timpur]

Sounds good guys :)

[marvinroger]

Let's all welcome the new homieiot/convention repo 😄

[ThomDietrich]

Wonderful. You might want to adapt the short description of the project to include "Homie".

I'd say the issues of this issue are settled. However let's leave it open as a reference.

[marvinroger]

Just did. Thanks to everyone! 👏

[lorenwest]

Just noticed the NodeJS implementation merged on Sept. 21 2017 didn't make it to the Home Page v2.0 or the new Implementations page.

Probably an artifact of repository movement - although if it were an accident, I wonder what other commits fell through the cracks...

[timpur]

@lorenwest Done :)

[lorenwest]

Would you mind also adding back to https://github.com/homieiot/convention/tree/release-v2.0.x ?

That's the version it was developed against. I'll update as soon as 3.x moves from WIP to LIVE.

[timpur]

@lorenwest Done, sorry should of thought about. Also you might want to define a version and link to one of the releases of Homie. https://github.com/homieiot/convention/releases :)