From ceb9cfeb344c5b07ec06689c94e27f092b10f44f Mon Sep 17 00:00:00 2001 From: Zearin Date: Mon, 18 Aug 2014 11:01:37 -0400 Subject: [PATCH 1/2] Add .editorconfig --- .editorconfig | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .editorconfig diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..97eec548 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +# EditorConfig is awesome: http://EditorConfig.org +# +# All EditorConfig properties: +# https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties + + +# Top-most EditorConfig file +root = true + +# This is a small project; currently, we +# use the same settings everywhere +[*] +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 From 8b9ec705a1c4b96ef7ccbbab8667a3f77fd47e40 Mon Sep 17 00:00:00 2001 From: Zearin Date: Mon, 18 Aug 2014 11:03:56 -0400 Subject: [PATCH 2/2] Regenerate index.html --- index.html | 99 +++++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 45 deletions(-) diff --git a/index.html b/index.html index beec6af5..029d314b 100644 --- a/index.html +++ b/index.html @@ -9,27 +9,27 @@

Keep a CHANGELOG

-

Don’t let your friends dump git logs into CHANGELOGs™

-

What's a CHANGELOG?

-

A CHANGELOG is a file which contains a curated chronologically ordered +

Don’t let your friends dump git logs into CHANGELOGs™

+

What’s a CHANGELOG?

+

A CHANGELOG is a file which contains a curated, chronologically ordered list of notable changes for each version of an open source project.

-

Changelog Example

-

What's the point of a CHANGELOG?

+

Changelog Example

+

What’s the point of a CHANGELOG?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Why should I care?

-

Well, because software tools are for people. If you don't care, why are -you contributing to open source? There must be a kernel (ha) of care -somewhere in that lovely little brain of yours.

+

Because software tools are for people. If you don’t care, why are +you contributing to open source? Surely, there must be a kernel (ha!) +of care somewhere in that lovely little brain of yours.

I talked with Adam Stacoviak and Jerod Santo on The Changelog (fitting, right?) podcast about why open source maintainers and -contributors should care, and the motivations behind this project. If -you can spare the time (1:06), it's a good listen.

+contributors should care, and the motivations behind this project. +If you can spare the time (1:06), it’s a good listen.

What makes up a good CHANGELOG?

-

I'm glad you asked.

+

I’m glad you asked.

    -
  • It's made for humans, not machines, so legibility is crucial.
    • -
  • One sub-section per versions.
    • +
  • It’s made for humans, not machines, so legibility is crucial.
    • +
  • One sub-section per version.
  • Versions should come with a release date in a sensible format: YYYY-MM-DD.
  • Changes should be grouped to describe their impact on the project:
      @@ -40,61 +40,70 @@

      What makes up a good CHANGELOG?

    • Security to invite users to upgrade in case of vulnerabilities.
  • Each section should be easily linked to — hence Markdown over plain text.
    • -
  • Write release dates in an international, sensible, and -language-independent format: 2012-06-02 for June 2nd, 2012.
    • +
  • Write release dates in an international, sensible, and language-independent +format: 2012-06-02 for June 2nd, 2012.
  • Order the releases reverse chronologically (latest at the top).
-

It's also good to mention whether the project -follows Semantic Versioning.

+

It’s also good to explicitly mention whether the project follows Semantic Versioning.

+

How can I minimize the effort required?

+

Always have an "Unreleased" section at the top for keeping notes on any +changes.

+

This serves two purposes:

+
    +
  • People can see what changes they might expect in upcoming releases
    • +
  • At release time, you just have to change "Unreleased" to the version number +and add a new "Unreleased" header at the top.
    • +

What makes unicorns cry?

-

Alright, let's get into it:

+

Alright…let’s get into it.

    -
  • Dumping a diff of commit logs. Just don't do that, you're helping nobody.
    • -
  • Not emphasizing deprecations: when people upgrade from one version to -another it should be painfully clear when something will break.
    • -
  • Dates in regionally-specific formats. Americans put the month first +
  • Dumping a diff of commit logs. Just don’t do that, you’re helping nobody.
    • +
  • Not emphasizing deprecations. When people upgrade from one version to +another, it should be painfully clear when something will break.
    • +
  • Dates in region-specific formats. Americans put the month first ("06-02-2012" for June 2nd, 2012, which makes no sense), while Brits -use a robotic-looking "June 2 2012", yet pronounce it "June 2nd, 2012".
    • +use a robotic-looking "2 June 2012", yet pronounce it "June 2nd, 2012".
-

There's more. Help me collect those unicorn tears by +

There’s more. Help me collect those unicorn tears by opening an issue or a pull request.

Is there a standard CHANGELOG format?

-

Sadly, no, but this is something I want to change. This project -contains what I hope will become the standard CHANGELOG file -for all open source projects, so take a look at it and please suggest improvements.

+

Sadly, no. But I want to change that.

+

This project contains what I hope will become the standard CHANGELOG file +for all open source projects. Take a look at it, and please suggest improvements!

What should the CHANGELOG file be named?

-

Well, if you can't tell from the example above, CHANGELOG.md is the +

Well, if you can’t tell from the example above, CHANGELOG.md is the best convention so far.

Some projects also use HISTORY.txt, HISTORY.md, History.md, NEWS.txt, -NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc. -It's a mess, that only makes it harder for people to find it.

-

Why can't people just use a git log diff?

+NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

+

It’s a mess. All these names only makes it harder for people to find it.

+

Why can’t people just use a git log diff?

Because log diffs are full of noise. Can we really expect every single commit in an open source project to be meaningful and self-explanatory? That seems like a pipe dream.

Can CHANGELOG files be automatically parsed?

-

It's hard because people follow wildly different formats and file names. -Vandamme is a Ruby gem +

It’s difficult, because people follow wildly different formats and file names.

+

Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project CHANGELOGs.

Why do you keep writing CHANGELOG in all caps?

-

You're right, that is a bit shouty. Maybe it's because of the de facto -convention that files pertaining to an open source project should be in -all caps, for instance: README, LICENSE, +

You’re right, that is a bit shouty. Maybe it’s because of the de facto +convention: files pertaining to an open source project should be in +all caps. For instance: README, LICENSE, CONTRIBUTING.

-

It denotes that these files are metadata for the project, similarly to -open source project badges they draw attention to -themselves as information people should be aware of if they mean to use +

This indicates that these files are metadata for the project. Much like +open source project badges, they draw attention to +themselves as information to be aware of if someone intends to use the project or contribute to it.

How can I contribute?

-

This document is not the truth, it's my carefully considered -opinion with the information and examples I was able to gather. Although -I provide an actual CHANGELOG on the GitHub repo, +

This document is not the truth; it’s my carefully considered +opinion, along with information and examples I gathered. +Although I provide an actual CHANGELOG on the GitHub repo, I have purposefully not created a proper release or clear list of rules -to follow like SemVer.org does for instance. This is -because I want our community to reach a consensus. I believe the discussion -is as important as the end result. So please pitch in.

+to follow (as SemVer.org does, for instance).

+

This is because I want our community to reach a consensus. I believe the +discussion is as important as the end result.

+

So please pitch in.