commit 7c70af6064dd70cda294ef53cf21b0209adad6f6 Author: Karsten Loesing <karsten.loesing@gmx.net> Date: Mon Nov 9 09:56:00 2015 +0100 Apply iwakeh's changes to CONTRIB.md. See #13166. --- CONTRIB.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/CONTRIB.md b/CONTRIB.md index 30f8680..069f7c7 100644 --- a/CONTRIB.md +++ b/CONTRIB.md @@ -27,12 +27,11 @@ We tried to keep the number of dependencies as small as possible, and we tried t metrics-lib currently has the following dependencies to compile: - - Apache Commons Compression 1.4.1 - https://commons.apache.org/proper/commons-compress/download_compress.cgi - - - JUnit 4.10 - https://github.com/junit-team/junit/wiki/Download-and-Install + - Apache Commons Compression 1.4.1 (https://commons.apache.org/proper/commons-compress/) + https://archive.apache.org/dist/commons/compress/binaries/ + - JUnit 4.10 (http://junit.org/) + https://search.maven.org/remotecontent?filepath=junit/junit/4.10/junit-4.10.... Code style ---------- @@ -41,7 +40,7 @@ We're using a code style that is not really formally defined but that roughly fo - We avoid tabs and favor 2 spaces where other people would use a tab. - We break lines after at most 74 characters and indent new lines with 4 spaces. - - Every public interface or method should have a comment, which should be a full sentence. We failed to turn these comments into JavaDoc comments, but we should fix that at some point. + - Every public interface or method should have a javadoc comment, which should be a full sentence. We failed to turn these comments into JavaDoc comments, but we should fix that at some point. There's probably more to say about code style, but please take a look at the existing code and try to write new code as similar as possible. @@ -61,29 +60,29 @@ We have to assume that applications don't update their metrics-lib version very Change log ---------- -We didn't have a change log for a long time, but we should totally have one if we want to put out releases. Here we're going to describe what deserves a change log entry and whether those changes are major or minor: +We didn't have a change log for a long time, but we should totally have one if we want to put out releases. Here we're going to describe what deserves a change log entry and whether those changes are major, medium, or minor: - - Bug fixes obviously need a change log entry, but it depends on the bug whether it should be listed as major or minor change. + - Bug fixes obviously need a change log entry, but it depends on the bug whether it should be listed as major or medium change. - - Enhancements that extend the API are also worth noting in the change log, though their importance would most likely be minor. + - Enhancements that extend the API are also worth noting in the change log, though their importance would most likely be medium. - - All enhancements must be backwards-compatible, so whenever we want to switch to a different interface we'll have to deprecate the existing interface and at the same time provide a new one that applications should use instead. Deprecating a feature would be a minor change that should be mentioned in the change log. + - All enhancements must be backwards-compatible, so whenever we want to switch to a different interface we'll have to deprecate the existing interface and at the same time provide a new one that applications should use instead. Deprecating a feature would be a medium change that should be mentioned in the change log. - - Enhancements that make the implementation more efficient or that refactor some internal code might also be worth noting in the change log, but very likely as minor enhancements. An exception would be ground-breaking performance improvements that most application developers would care about, which would be major enhancements. + - Enhancements that make the implementation more efficient or that refactor some internal code might also be worth noting in the change log, but very likely as medium enhancements. An exception would be ground-breaking performance improvements that most application developers would care about, which would be major enhancements. - Whenever we add a new dependency, that's clearly a major change that needs to be written into the change log, because applications will have to add this dependency, too. - - Removing an existing dependency is also worth mentioning in the change log, though that's rather a minor change that doesn't force applications to act that quickly. + - Removing an existing dependency is also worth mentioning in the change log, though that's rather a medium change that doesn't force applications to act that quickly. - - Any simple code cleanups, new tests, changes to documentation like this file, etc. obviously don't require putting in a change log entry. + - Any simple code cleanups, new tests, changes to documentation like this file, etc. only require a summary change log entry and will lead to a minor version change. Releases -------- -As mentioned before we didn't put out releases for far too long. But we're about to change that. As a rule of thumb, we should put out a new release of metrics-lib soon after making a major change as listed under "Change log" above. If we're planning to make more changes soon after, let's wait for them and make a release with everything. But we shouldn't let a major change sit in an unreleased metrics-lib for more than, say, two weeks. In contrast to that, minor changes can stay unreleased for longer, though they don't have to if we want to use them in an application sooner. +As mentioned before we didn't put out releases for far too long. But we're about to change that. As a rule of thumb, we should put out a new release of metrics-lib soon after making a major change as listed under "Change log" above. If we're planning to make more changes soon after, let's wait for them and make a release with everything. But we shouldn't let a major change sit in an unreleased metrics-lib for more than, say, two weeks. In contrast to that, medium changes can stay unreleased for longer, though they don't have to if we want to use them in an application sooner. Minor changes can be collected and usually will be released with changes on higher stages, but when necessary they can be released earlier. -Regarding version numbers, we'll start with 1.0 and bump to 1.1, 1.2, etc. for each backwards-compatible change. When we remove a previously deprecated feature, making a backwards-incompatible change, we'll bump to 2.0. +Regarding version numbers, we'll start with 1.0.0 and bump to 1.0.1, 1.1.0, 1.2.0, etc. for each backwards-compatible change. When we remove a previously deprecated feature, making a backwards-incompatible change, we'll bump to 2.0.0. Packages