Who is this project for?

[olivierlacan]

Who is this project for?

[mbrand12]

Currently I see this project more as a set of practical guides to make the changelog more understandable and accessible to whomever the audience is, what they actually put in sections and to which level of detail they go is up to them.

Weather you have two or more different changelogs, the basic idea for me is to follow the guidelines when it comes to putting dates, putting compare links (if the repo is on github), sectioning your changes to "added", "removed" etc.

Also how you have generated that change log (meaning that if you have a master changelog that is filtered/rendered differently depending who is accessing it) is also up to you.

Here is an example:

While this chagelog is comprehensive however when formatted following this project guidelines it contains much more information while not really changing the content.

Also one of the good side effects of using these guidelines is that when identifying what change belongs in what section it also helps when determining the release version number.

This project, in my opinion should be used like semantic versioning is used. With semantic versioning you don't care what is in the project you only care that a major version number will change when either something is removed and it will cause something to break or some new feature worthy of a major number change.

And here is whnere this project comes in for me, when I want to quickly see what is the breaking change instead of reading the whole changelog changes list for that version I just jump to the subheading "Changes" and see if there are any [breaking] tags, for example.

And once this or any other format for changelog has became a more wide used standard imagine if for example you can set bundle to display only breaking changes on gem install or anything like this. The reason why this would be possible is because of the standardised way of writing changelogs.

With GitHub for example, thanks to the compare links, the commit messages actually complement the changelog since you can view the full commit message and implementation details.

Though while I agree that filtering a master changelog is not a bad idea, using commit messages for changelog messages is a bad idea (as noted in the readme of this project), since people use far to many different commit styles.

So the goal, in my opinion, of this project is just to make those changelogs more readable by motivating everybody to use the same or at least similar format, while how you filter you changelog for a different audience, or weather you maintain more than one in the same project is mostly up to you.

I hope I haven't missed the point of your question by allot :)

[olivierlacan]

This project is for software developers.

[olivierlacan]

I really don't mean to dismiss this question. I'll read both of your posts a bit later but I wanted to answer the question as soon as possible.

[lambda]

That answer is a little too short to answer my question; and actually, I'm left wondering which question you answered, because just reading the title my question could be interpreted ambiguously, and you indicate that you haven't read the full post.

I'm not asking about who this specification is intended for; it's obviously intended for software developers writing a change log of their software. I'm curious about who the intended audience of the change logs that it describes is; is that audience intended to be other software developers on the same project, other software developers using an API provided by the project, technical users, downstream packagers, or non-technical end users. More than one may be in scope, or perhaps the intent is to provide a specification for change logs that contain all of the information in a way that could be trimmed down for different audiences (as some of the discussion about marking certain changes INTERNAL in order to filter them out for release notes).

I'm asking this question because I had some other issues to bring up for clarification or patches to send, but some of them only make sense depending on the intended audience of the change logs. I'm trying to figure out what is in scope for this project.