[proposal] Milestones for Versioning

[simonnagl]

I like to make some proposals.

Grouping enhancements and bugs in milestones will give the following benefits.

1. People who open a issue can see when it will be fixed/implemented.
2. People who want to contribute can better choice on what to work.
3. People who do not want to build from source can see when a feature will be released.
4. We start something like a release cycle.

Above when does not mean a time, but it means in the near feature, in the next release...

[titpetric]

Agree for versioning, docker image would also benefit from some kind of stability, apart from latest. I'd recommend a branch for each version, following some pattern like release-X where X can be /^[0-9.]+$/ (1.2.0) or /^[0-9.]+/ (1.2.0-rc1). This can be caught with rules on Docker hub.

[titpetric]

Actually, I see that tags are already created. I'll check if I can include them in docker hub. Disregard my comment about branches, seems it's not a requirement, just an option.

[ktsaou]

@simonnagl, I like your proposal.

My unofficial plan at this phase was to release every about 2-3 weeks. This is required mainly due to bugs (even the v1.1.0 release has significant bugs - the dashboard of v1.1.0 does not work on mobile browsers) or key new features.

My cause with netdata is to prove that performance monitoring can be done with high frequency data collection (per second) and scaled out efficiently, with just minimal centralized functions. To deliver this, I should work in areas like optimization of the database, snapshots, registry, annotations. I now understand that also health monitoring (alarms, etc) is a core function that should be embedded in netdata.

I am thrilled that if netdata can deliver on this promise (scale out), it may become an open, global monitoring system, free for everyone. Since minimal centralized functions will be needed, this seems feasible - the cost for the centralized functions can be insignificant, or even covered with donations by companies that use netdata. Of course this will not prevent anyone from having his/her own installation of the centralized functions.

At the same time I understand that the success of netdata depends on the availability of data collectors, its packaging, new visualization techniques, dashboard editors, documentation. I even experimented a bit with blogging when I wrote a few of the pages found at the wiki (DDoS protection monitoring, You should install QoS on all your servers, etc). Future blogs could be "Monitoring Linux containers effectively", "Get to know your mysql/postgress/X database server", etc, Such blogs/articles spread the word, expand the user base and attract developers willing to contribute.

A lot of people (like you guys) have helped netdata a lot during the last month. Actually I am impressed by the wide and quick adoption of netdata. However netdata needs a bigger developer base to commit on the delivery of features.

Until we reach that point, It would be probably better to just set the beat: release once per month, for the following months, increasing the minor version number: 1.2, 1.3, 1.4, - or even the May release will be 1.5, December's 1.12, then on Jan 2017 we will go to 2.1 and so on.

If we have such a beat, we could announce it, use the issue tracker assignments to let everyone know who is responsible for an issue and developers can grab feature requests or bugs and commit to deliver them by one of the following releases. I will do the same.

Of course I am open to any other ideas too...

[ktsaou]

@philwhineray @glensc @mcnewton @alonbl @fredericopissarra have a look. Your opinion matters.

[simonnagl]

I do not know if releasing in a fixed beat is a good idea.

1. It is more likely to intodruce bugs. Currently we do not have a testing envoirement which can limit the probability a change introduces bugs. If we want great accepted software we should avoid bugs. Although we need to implement bigger features on different branches then if we don't want to release half working things.
2. Release numbers do not say anything about the content of the release.

I think also without having a big developer base yet, netdata should get some rules:

1. How to contribute, how to document.
2. A list which groups and priorises to do's. (This can be done with tags and milestones or in the wiki.)

[philwhineray]

I don't think introduction of bugs is likely to be particularly related to the organisation of releases; they will relate to the rate of change. Bugs will only be squashed by testing, good review or lack of changes. With git, everything is a branch and I would expect pull requests to be accepted when they are ready (whatever that means), not before.

I agree that something (wiki page or bug) to list high priority contributions would be useful. More so than a which roadmap which might tell you to expect something but doesn't guarantee anyone does the work and might have the effect of discouraging people from contributing changes they find useful enough to create but are not "on the list".

Since the code is still young and moving quite fast I think a short, possibly semi-fixed cycle will work well, so that people know that if they try to contribute some code and it is "not ready yet", then they will not have to wait months to see it included in a release.

I understand the desire to provide some certainty but I think when a project is made up of volunteers, then certainty is mostly an illusion. I can point to myself and how my time has vanished recently but I occasionally get back a few hours or a day or so. Any attempt to work to a roadmap is doomed to failure for me.

If you want something more formal but that caters for a wide range of contributors, then a bug or page tracking what is being worked on and expected to go into the next release (signed off or nearly signed off) and possibly the one after that (code exists / someone is working on it) would provide some idea... but as usual it requires someone to put effort into curating the information.

If there are enough testers, take the linux kernel idea of having a "next" branch which tracks pull requests mooted for inclusion so it is all in one place ahead of a release.

[titpetric]

I'd also skip fixed release dates in favor of actual milestones. As a good example (in my opinion), take look at the golang/go repo. PR's and feature requests are sorted in explicit versions, and they may or may not be included in a version - depends on stability.

1. development is always done on the same branch (master, or even explicit version for example)
2. when a release is ready, create a branch or tag with explicit version a) branch is slightly better as it allows hotfixes
3. if you're making a big rewrite it's better to branch (v2.0).

The reason for explicit tags (and not time based tags) is that they specify what kind of changes happen in APIs. If people write software which might depend on some standard output available in 1.1, they can be sure that the change to 1.2 might incur some minor changes, and that the change to 2.0 is a complete rewrite of existing interfaces. Think of versions as impact: [major].[minor].[patch]. So when you're changing 1.0.123 to 1.0.134 it's a bugfix release, 1.0 to 1.1 however is change in functionality. A time based approach doesn't consider these factors.

Also: bugfix/patch releases are mostly for posterity - I usually just put a timestamp as the patch version, any sequence will do. Bump minor version with change of functionality that might break existing clients/compatibility.

[glensc]

indeed i'm impressed the netdata quick adaption, finally those 700+ forks have fired back as issues, and pull requests (i've subscribed to this project all activity).

about releases, i wouldn't use strict release plans, just release when you have time and feel the changes depart from last release that release is necessary to have documentation and last release matching.

[philwhineray]

Just to be clear, I'm not advocating tags based on timestamps, just that having a target date for making a new release wherein things are included/not included according to readiness, rather than having a fixed feature set determine what constitutes a release.

Versions would be incremented along the lines of http://semver.org/ and yes, a new major release would result in a new branch to allow continued development of the old version.

At some point the rate of change will likely tail off and then it makes more sense to either target completion of specific features or some other system.

On 4 May 2016 at 08:38, Tit Petric notifications@github.com wrote:

I'd also skip fixed release dates in favor of actual milestones. As a good example (in my opinion), take look at the golang/go repo. PR's and feature requests are sorted in explicit versions, and they may or may not be included in a version - depends on stability.

1. development is always done on the same branch (master, or even explicit version for example)
2. when a release is ready, create a branch or tag with explicit version a) branch is slightly better as it allows hotfixes
3. if you're making a big rewrite it's better to branch (v2.0).

The reason for explicit tags (and not time based tags) is that they specify what kind of changes happen in APIs. If people write software which might depend on some standard output available in 1.1, they can be sure that the change to 1.2 might incur some minor changes, and that the change to 2.0 is a complete rewrite of existing interfaces. Think of versions as impact: [major].[minor].[patch]. So when you're changing 1.0.123 to 1.0.134 it's a bugfix release, 1.0 to 1.1 however is change in functionality. A time based approach doesn't consider these factors.

Also: bugfix/patch releases are mostly for posterity - I usually just put a timestamp as the patch version, any sequence will do. Bump minor version with change of functionality that might break existing clients/compatibility.

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/firehol/netdata/issues/365#issuecomment-216767437

[ktsaou]

ok. I also agree that semver.org compatibility is better. So, how do we proceed?

[simonnagl]

You guys convinced me that maby having features on fixed milestones is a bad idea. We cannot guarantee any timing in releases. Maby telling the users somewhere that we try to release once a month is a good idea. With using Semantic Versioning I do not see problems for that.

For using semver we should once define what is in our current public API. Configuration? REST? PLUGIN interface?

I would like to contribute to netdata documentation too. Currently (git wiki) it is not possible for everyone because pull requests do not work for it.

[ktsaou]

I would like to contribute to netdata documentation too. Currently (git wiki) it is not possible for everyone because pull requests do not work for it.

What would be nice is to use jekyll or something else to publish it on github pages. We could have charts from the demo installations into it, which would be... wow! We could also have analytics to know what the users use...

A simpler solution could be a simple clone of the wiki to put it in a doc/ directory in netdata and automate somehow its publication via github hooks.

[philwhineray]

I would like to contribute to netdata documentation too. Currently (git wiki) it is not possible for everyone because pull requests do not work for it.

Quite. As @ktsaou says it is possible to clone a wiki, which means one could use old-fashioned patches... git clone git@github.com:firehol/netdata.wiki.git. I think the github solution is to work on a jekyll site though. Personally, I think that would be less fragile than hooks to push the wiki to a second location... better to just have a link to the wiki in suitable places.

Meantime, @simonnagl , if you apply to join the project I expect it will be accepted. You can be added to the netdata team which will allow write access to the wiki direct, which should be fine: I think they were locked due to vandalism, not because we want to stop edits more generally.

[glensc]

On 05.05.2016 03:20, Costa Tsaousis wrote:

A simpler solution could be a simple clone of the wiki to put it a |doc/| directory in netdata and automate somehow its publication via github hooks.

or as wiki is git repo, create separate project that mirrors to wiki's git

https://github.com/firehol/netdata-doc.git@master -> https://github.com/firehol/netdata.wiki.git

glen

[simonnagl]

@philwhineray Thank you for the invitation.

Nevertheless I think it is needed that everybody can contribute to the wiki in a save way. I know about old fashiond patches but I like the idea of @glensc more, if this is possible.

[glensc]

@simonnagl you mean my idea of having git repo "netdata-doc" which on master branch push updates wiki?

i think that can be accomplished with Web Hook that posts to some hosted server which does the git pull from netdata-doc and push -f on netdata.wiki, but that means nobody should edit via native github wiki interface, two way merge ends up as a mess.

if the documentation is structured as documentation format, it's likely better to use https://readthedocs.org/ instead.

[simonnagl]

Yes, I did mean that. readthedocs.org looks even better. I will open a new issue to discuss where to document what.

[titpetric]

Just as an option, I've used mkdocs successfully in the past. Doc would be structured in markdown files in a normal git repo + generates output with readthedocs theme. It would most likely take a branch, or just a docs/ folder inside the repo, which enables PRs. Generating html docs for gh-pages would need to be off-github however, i think only jekyll is supported, but there might be other options for docs if you need to manage them via a gh-pages branch.

[simonnagl]

Currently I like the idea of jekyll sites most.

1. They are easy to maintain for everyone.
2. We can publish them easily on github pages while being able to have to run it local or anywhere else. https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/