Add releaser script

[marvinroger]

This script is automatically ran on every commit on develop.

The script:

• Goes through all commits done on develop since the last release

• Analyzes all commits prefixes (in this form: prefix: The commit message to determine which version bump to do. The prefixes are:

  • BREAKING for breaking changes (MAJOR bump)
  • Feature for new features (MINOR bump)
  • Fix for fixes (PATCH bump)

  The highest bump is then picked.

• Checks if there's the [release] text in the body of one of the commits. If so, continue, if not, abort

• Builds the convention:

  • Copies convention.md to README.md, replacing the date and version placeholder
  • Copies the LICENSE file

• Pushes the resulting build to master

• Create a GitHub release pointing to master, with the changelog extracted from the commit messages

[davidgraeff]

1. Could you please make it possible to have the script in another repo, like the webpage and webpage script.

2. Tags should belong to a linear history of changes and tag a particular point in time, in my opinion. With your history rewrite approach every tag is a dead end, like tree branches. I would rather see the tool just applying all commits to the master branch and adding the computed tag in the end. That way develop and master never diverge and each tag points to a specific point in time.

[marvinroger]

@davidgraeff

1. It makes sense, indeed.

2. When you build a website on gh-pages, you just build "dead-ends", right? That's the same thing here, except we're not building a website, but a markdown file. The built convention contains a comment at the top with the source develop commit SHA, making it possible to compare changes between two conventions.

[davidgraeff]

2. There is one difference. You are tagging the history. And with a later release you are overwriting the master ref which leads to dangling tag refs. That's not how git is supposed to work for tags and I don't like this solution.

[marvinroger]

I see. It might be over-complicated, just to have 3.x.x replaced with the actual version. @ThomDietrich @Thalhammer @timpur what do you think?

[Thalhammer]

To be honest, while it would really be a cool thing, I personally think there shouldn't be that many version changes to make this necessary.

[timpur]

Not sure im of use here, as long as no accidental releases occur im happy with what ever you guys decide.

[ThomDietrich]

Hey guys,
I am reluctant to the control-via-commit-message method. I can already see someone forgetting or mistyping a commit message and wild amend-force-pushes to fix that. Anyhow, if this is the method you want to work with, I guess we can make it happen. One benefit this method offers: we need to clarify the level of version bump before merging a PR.
Still I wonder if it would have been easier to just create a version tag after every PR merge. This is probably one of the easier aspects of the whole convention development...
Regarding the (mis)use of tags: I'll need to look at the sources again. Last time I was involved we all agreed that there should not be a develop branch anymore 🙃

[davidgraeff]

Actually there is no "develop" branch as in the original sense, it has taken the role of "master" within this repo. But the name is better, so maybe stick to it and just delete "master".

The version can unfortunately not be bumped after every PR, that would cause a lot of majors during a development phase. A release should happen every now and then and the release guy or a script has to determine the next semver compliant version.
I have proposed a small shell script in #123 that determines the next version and creates a tag.

[ThomDietrich]

I agree with @davidgraeff. You are effectively replacing the complete master branch with a new one-commit-(...I don't even know what to call this, it's not even a tree as @davidgraeff said, it doesn't have any relation to other git objects). This is indeed very bad. Amending a public commit should be avoided, rewriting history should be a last resort, replacing the complete history is just ....no.

What is the purpose of the develop and master branch? Why didn't we stay with master-only and the version tags system I proposed in #46. I am not saying that this was the perfect arrangement but why all the overhead and a script that will be hard to maintain and troubleshoot?

[Thalhammer]

The version can unfortunately not be bumped after every PR, that would cause a lot of majors during a development phase.

I don't think that @ThomDietrich wanted to bump the major version after every PR. A version bump int the way I understood it would also be 3.1.1 => 3.1.2
Do we really need to have the version inside the document in GIT ?
Maybe its good enough to mark individual commits with a tag and add a script in the main folder that fetches the latest tag and replaces the placeholder (but only in the local copy).

[davidgraeff]

We can also remove the placeholders all together and let the website builder add a header that looks a bit more professional (and boring) like in:

Internet Engineering Task Force (IETF)                         C. Newman
Request for Comments: 8437                                        Oracle
Updates: 3501                                                August 2018
Category: Standards Track
ISSN: 2070-1721


           IMAP UNAUTHENTICATE Extension for Connection Reuse

The advantages is: This will work for every currently published version. Older versions like 3.0 and 2.x don't have the placeholder at all right now.

[ThomDietrich]

Yes @Thalhammer I meant every version change.
And yes the placeholder in the document ("v3.x.x") was always only meant more as a general information and the exact version is marked in git tags. @davidgraeff I think that would be a good approach, I thought that's already what you are doing!?

But the name is better, so maybe stick to it and just delete "master".

Seems controversial but I get your point. However as in general git terms "master" is the main branch and develop only a temporary side-branch to master, this could confuse people. I'm not specifically against this, just saying...

The version can unfortunately not be bumped after every PR, that would cause a lot of majors during a development phase.

Not sure what you mean. Every PR commit to the main branch (be it master or develop) should entail a version bump && git tag.

[davidgraeff]

@ThomDietrich I'm going to tackle every problem of the spec at the moment: I have started with slimming it down (version 4), reworking arrays (version 5), reworking $stats (version 6). If we really bump the version with every PR, nobody will take this spec serious anymore.

Instead multiple PRs with multiple issues are resolved and at some point a spec update happens.
That's what you need to do if you want semver and keep a stable major for a time, I guess.

[lorenwest]

If we really bump the version every PR, nobody will take this spec

serious anymore. Correction: If we change the spec often, nobody will take this spec serious anymore. We have to understand the actual cost of change. People have invested time into Homie, and change for the sake of change (or someone's perception of goodness) will actually be the death of Homie. Instead of changing, consider adding. As long as additions are optional they don't break the spec. If you're retiring existing functionality, call it out as deprecated in a future release. Remember, this is IOT. There are devices in the real world that have Homie burned into them, and may have to be thrown away based on your decisions.

…

On Tue, Nov 6, 2018 at 5:29 AM David Gräff ***@***.***> wrote: @ThomDietrich <https://github.com/ThomDietrich> I'm going to tackle every problem of the spec at the moment: I have started with slimming it down (version 4), reworking arrays (version 5), reworking $stats (version 6). If we really bump the version every PR, nobody will take this spec serious anymore. Instead multiple PRs with multiple issues are resolved and at some point a spec update happens. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#119 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAWzIsNCX5elbsNCSJ20l52Sk_2eAJveks5usY7EgaJpZM4YCmax> .

[davidgraeff]

@lorenwest The convention was not fully thought through in the beginning, it evolved from a personal esp8266 microcontroller project. And some changes are just necessary now, like talking about arrays, $stats, how to perform OTA and so on.

Those are all breaking changes and therefore should be done in one go, so that ideally Homie can express every use-case and is not much work to implement.

[lorenwest]

I would consider the ESP8266 project a reference implementation. If clarifications are necessary and compatible with the reference implementation, that does not require a major version bump.

It's ok to add features and clarifications that didn't exist, but nothing we do should render existing 8266s incompatible without a damned good reason. Otherwise this will be looked at as somebody's playground for imagining the perfect spec.

Once a spec is released (as this has been), there's a responsibility to consider the existing community.

[davidgraeff]

Actually the 3.x is already incompatible to the esp8266 project which implements 2.1.

An example: The openHAB controller is 3.0 and cannot discover esp8266 clients. So there is a fragmentation existing.

That is why I wanted the rest of the topics to be discussed soon, so that someone can tackle the esp8266 project and bring it up to speed.

[ThomDietrich]

If we really bump the version with every PR, nobody will take this spec serious anymore.

That is indeed correct and I agree that major changes can be collected before bumping the major version number once. I did never disagree with this approach and think this sounds like a good plan.

@lorenwest you bring forth good points. However remember that the convention underwent quite some discussion in the last couple of months (with a pause in between). Version 3 was a good first step to streamline the messy status-quo from before but many very valid issues with the convention were still not resolved. I'm very happy to see @davidgraeff now taking the lead in pushing these issues.

We all should concentrate to solve the existing issues quickly so that a stable and future ready version 4 (or whatever version number it will hold) can be released to the public for broad adoption.

[timpur]

IMHO, im not seeing the value of automated releases. I worry this will cause more problems than it solves. Some one will have to make sure there the PR's have the right and exact wording for this to work. Also i believe that things like Major releases should go through a PR and be reviewed by min of 2 (prefer 4) people. Just to ensure that we get right every time. Id not like to end up where some one released a major version a little to early and now we have to wait another major for a breaking change that was almost complete. I think a planing (road map) is essential for Homie to succeed.

[Thalhammer]

@lorenwest Just because we change the spec from version 3 to 4 doesn't render all v3 devices useless. You can easily handle both versions on the same broker at the same time. It only adds complexity to controller implementations, but since those are running on beefier hardware most of the time it's not a huge deal. I do however agree that it makes the convention look bad if we change major to often. I don't feel like a major change should happen more than once per year. Never if possible.

[davidgraeff]

I would say we keep the prefix convention for commit messages (BREAKING:, feature:, fix:) but use a manual release process for now. That seems to be what the majority of people are saying here.

I'm closing this PR then.