Handling of Public vs Internal changes

[masukomi]

This is somewhat related to issue #2

We have a SAAS app. We make many changes. We want these to be in the Changelog. We need to communicate what's changed to the client, but they don't need to know about refactorings or other things that we find notable but have no customer facing effect.

Proposal

In each release support the current format as well as the concept of "Public" and "Internal" sections. Automated tools could be set to simply ignore anything under an "Internal" heading when generating documentation for public consumption.

An example (noting that most of the time only some of these would be present / filled out):

## 0.0.4 - 2014-08-09
### Public
#### Added
- blah blah

#### Changed
- blah blah

#### Removed
- blah blah

### Internal
#### Added
- blah blah

#### Changed
- blah blah

#### Removed
- blah blah

[masukomi]

I've been thinking about this more, but the more I do the more i realize the implementation above would just complicate processing. You'd have to remove the ### Public header and decrease the header level by one of everything under it before giving it to the public otherwise it would imply there was non-public stuff and they'd get all curious about it.

Leaving everything as it is in the current guidelines, but also adding an ### Internal section would work. The problem with that is that the ### Internal would be an h3 just like added / changed / removed which implies it semantically equivalent. It, of course, is not. It would also complicate processing because then you couldn't treat all the h3's in a section equivalently. You'd have to constantly be checking "wait... is this the 'internal' section?"

With those issues in mind the best I've come up with so far is to insert an hr ( -------------------------------) and then have a ### Internal section with added / changed / removed subheads. I'm not thrilled about it being an h3 but I don't have a better suggestion.

[pdurbin]

refactorings or other things that we find notable but have no customer facing effect

Right. Sometimes you want a place to write down the stuff that developers much do to continue working, such as:

• drop your database and start fresh
• run this SQL update
• update your Solr schema.xml after pulling the latest code
• upgrade to the latest version of Tomcat
• add this JVM option to your setup
• ...

This isn't customer-facing stuff. It's in-the-weeds developer stuff that's important for developers to keep their dev environment working. Some of it will become user-facing in the end, and that's what a changelog is in my mind, but there's also a need for a separate file (or something) that developers can look at to see what they have to do if stuff is broken after pulling the latest code.

[bramdevries]

I would suggest using a tag based approach, internal changes get prepended with an [internal] tag, public changes don't have to be prepended

### Fixed 

* Fixed a bug involving feature x ( closes #1)
* [internal] Fix issue with test database not being seeded properly

[masukomi]

Right. Sometimes you want a place to write down the stuff that developers much do to continue
working, such as:

drop your database and start fresh

• run this SQL update
• update your Solr schema.xml after pulling the latest code
• upgrade to the latest version of Tomcat
• add this JVM option to your setup

I have to disagree on that. While I agree that this is valuable information that should be captured somewhere, I believe that the changelog is absolutely not where it belongs. The changelog should represent changes that have been made to the project, not instructions or other tangental notes related to those changes.

We keep a separate test plan document that we update in parallel with the change log, and that captures most of the info we need. The stuff you describe that relates to keeping your environment working... that'd go in an e-mail, and maybe also in the body of the commit message related to the change.

[akhy]

@bramdevries I would suggest using a tag based approach, internal changes get prepended with an [internal] tag, public changes don't have to be prepended

seems pretty simple and practical 👍

[lunemec]

@pdurbin this should be in UPGRADING file separate from CHANGELOG. See #34

[lunemec]

@akhyrul @bramdevries Agree 👍 The tool should take care of exporting public version .. see #51

[olivierlacan]

While I have used [INTERNAL] tags (on individual changes as @bramdevries demonstrated), it was to mark potentially irrelevant changes to end-users in order to parse out a different version of the changelog and use it as release notes.

After doing this for a few months I realized that release notes and change logs have purposes but ultimately different audiences (people using software vs. people depending on software) and transparency requirements when it comes to communication: a change log needs to disclose any relevant changes because the most insignificant change may introduce a regression, while the same insignificant change may introduce a bug it's unlikely that it will ever be communicated in release notes.

While writting this paragraph I realized that we perhaps need to differentiate release notes and change logs better to help others understand the difference.

Now back to my point, I'm not convinced (yet) that [INTERNAL] changes belong in a change log but if a majority agrees that it's a good idea to extract out a public version that filters out [INTERNAL]changes (see #51) then I'm more than fine with that.

[lunemec]

The public version was meant as version for the users - or the client if they don't require implementation specific details. This might not be relevant for open source, but could be relevant for closed source platforms which may implement this.

A note: the [INTERNAL] tag with note to implementation details could link to the commit and the file changing this. This is however only information useful for the programmers, thus the option to filter it out.

[bramdevries]

While I have used [INTERNAL] tags (on individual changes as @bramdevries demonstrated), it was to mark potentially irrelevant changes to end-users in order to parse out a different version of the changelog and use it as release notes.

My idea was to do exactly this, the only use of the [internal] tag would be to inform other developers on a project about a change. This information is useless to end users so it would have been filtered out.

At work we include changelogs whenever we create pull requests, eventually creating private changelogs out of those notes. In the end these will be converted to public changelogs (for clients/non-technical persons_

[nbibler]

I think I'm ok with the idea of an [Internal] tag / flag. But, I really only see it as a privately-adopted means to a more generalized end.

The rationale for tagging items as internal, if I'm understanding, is to allow another tool to later filter those lines away in order to display a redacted version of a changelog for a particular audience. I can certainly see a use case where a SaaS has to report to their immediate client some platform changes, but then report a different set of public-facing changes to their client's customers. Stripe (a SaaS) -> ecomm site (an immediate SaaS client) -> paying card holder (a SaaS client's customer).

No matter how you get there, you're merely providing two changelogs from your SaaS. Whether they're generated via a tool or manually kept in sync by just keeping two changelogs is just an implementation detail that shouldn't have a project-wide specification, IMHO. What if tomorrow Company B services 3 categories of end users (instead of the 2 as you've described)? What if you need to later add some detail to the public changelog that the internal one does not need?

There's nothing wrong with having two changelogs in one project. In fact, it demonstrates an understanding of your audience and provides a significant service by isolating information to only what matters.

[masukomi]

speaking specifically about changes, not upgrade instructions, developer notes, or anything of that ilk.

I think that 2 files is a bad idea. In our co every new Pull Request must be accompanied by a change to the changelog because it's trivial for the developer knows exactly what happened and a Pull Request is the smallest unit of change worth communicating to others.

Here are the problems to consider with changelog maintenance and internal vs public records

1. nobody particularly wants to go update the changelog
2. internal vs public introduces a choice
3. people aren't going to want to have to make that decision because they might get it wrong
4. people will get it wrong
5. Who is "internal"

Let's deal with 5 first.

I think how / why you make an internal designation is important. In our case we ONLY mention things at a very high level in the changelog. Our intended audience is client managers / account reps, and internal teams who use the app. We want to let them know about everything that we've done. Some things don't need to be communicated to the clients / end users though. Like bug fixes to problems they weren't even aware of. We want to have a document that that anyone in our co could read and derive value from, but we also want it to be easy for client managers to create / have a version that can be shared with end users.

Your uses may be different, but they'll probably have a significant impact on your usage of this designation, when it's made, and what you do with the results.

4:

If you've got 2 files then:

• you've got to remember to verify the contents of two files and make a determination if each item is in the right one
• when something isn't you have to cut and paste, and possibly decide where in the list it should go
• you've got to save and check in multiple files. (every additional file is a potential thing that can be forgotten).

If you've got one file you just scan one list going yup, yup, nope (delete), yup, nope (type insert). then commit the changes to the single file.

3:

it's not just a question of internal versus external, now i have to decide which file to open. Yeah, i'm picking nits, but trust me, minor cognitive roadblocks build up. You want to remove every one you can so that people have less reason to avoid the task.

2:

nothing can be done about having to make a choice

1:

you could make it one person's job to write the changelog, but then you've got to have the developers communicate with that person and explain what they did. Alternately, you could do what we do and just have every Pull Request require a Changelog entry to get merged*. It's far less effort for the developer to write a sentence than many sentences to explain the details that any receiving human would want.

my vote

No matter what, I think the solution to this particular problem should remain within a single file.

I like the [internal] tag idea. I think before implementing it we should consider what other tags people will ask for once that shows up. Not, to get ahead of the curve, but because it may help inform the question of if having a tag at the beginning of each line is a good idea.

Internal results in a simple line redaction via tooling. Ok, easy enough. What about something like [paid] as in a new feature that is only mentioned to paying users. Or maybe there are classes of users and you want to note different things for them. What about [breaking] for features that break existing behavior? How would those things play out in tooling? What about a tag that indicates which team made a change, or which team should be made aware of it? I'm not suggesting these are all good ideas. They're just things i can see some teams wanting. Maybe it's just some form of highlighting and rules based redaction. Maybe it results in reordering on display? HTML version with a tags sidebar where clicking the tag you want only shows the related entries? Is multiple tags per line something worth supporting?

* turns out constant commits to the changelog, where everyone is adding a line to the bottom of the same list results in frequent conflicts. Very annoying. We need to write a custom git merge strategy for the keep a changelog format.

[kossnocorp]

I'd propose *Internal*:, in order to be consistent with **BREAKING**: proposed in #41.