Create GOVERNANCE.md

[waldyrious]

see #81 for context.

[waldyrious]

Do not merge yet. I will add content to the release section shortly.

Update: this is now ready for review. Pinging @Xymph and @hamstar for feedback :)

[Xymph]

The phrase we previously agreed on and used was "Current development".

[waldyrious]

I can't recall how detailed the previous discussion was (I did a search but couldn't find it), but the rationale here is that if we're claiming/recommending Keep a Changelog compliance, then we should use the heading they propose, i.e. "Unreleased" (which IMO is also more explicit than "Current development", and fits better with the other headings), unless there are strong arguments to deviate from it.

[Xymph]

Discussion led to issue #48, and the resulting commits were approved without further discussion it seems. So I guess our agreement was more implicit than I remembered.

Does adhering to a standard mean that we have no creative freedom to deviate in how we word something? Precedent does exist, although I've not found many more examples.
Anyway, I like "current development" better because it has a more positive and active connotation. Many words starting with "un" feel less so.

How exactly do you mean "fits better with the other headings"?

[waldyrious]

Discussion led to issue #48, and the resulting commits were approved without further discussion it seems. So I guess our agreement was more implicit than I remembered.

Ah, yes, thanks for the links :)

Does adhering to a standard mean that we have no creative freedom to deviate in how we word something? Precedent does exist, although I've not found many more examples.

I'd say we can deviate from the standard, if sufficient motive exists.

Anyway, I like "current development" better because it has a more positive and active connotation. Many words starting with "un" feel less so.

I can agree with this argument, but I'd rather we picked a different section name that still conforms to it. I'm afraid "Current development" may not be sufficiently clear. It certainly feels slightly awkward to my (non-native English speaker) ears, for the meaning it is intended to have.

How exactly do you mean "fits better with the other headings"?

I meant that all headings are version this, version that; so it would logically make sense (IMO) that the top heading is "upcoming version", "next release", "unreleased [version]", or something to that effect. Do any of these (or a variation thereof) appeal to you?

[Xymph]

I see, thanks for the clarification. TBH, none appeal much to me, nor appall me, but it took me a while to realize (or remember from the time when I choose "Current development") why.

On Git(Hub) the formal meaning of "release" is to tag the current state of affairs into something fixed, no longer in flux. But to me the very act of putting something online is already "releasing" it, in the practical meaning. That's how I worked with my previous, non-gitted projects; I didn't put anything online until it had enough quality and quantity to be version-able.

So "unreleased" or (worse) "next release" feels like a misnomer because the content under that heading is already in the master branch, is already "out there". I guess I'm still not quite used to GitHub's meaning of "release". To my equally non-native ears my original choice of header sounds like a adequate description of the entries below it, which can remain in a state of flux until tagged (see the number of PRs until WikiFile was ready).

But if you're still feeling awkward about it, then I'm fine with simply sticking to the Keepachangelog standard verbatim. We are, after all, working on GitHub now. 😄

[waldyrious]

I see what you mean, but yeah, I guess people do end up getting used to the github model. I never even considered any other interpretation until you brought this up :)

Now that I've thought about it more explicitly, I do believe this is a better way of working with FOSS, as it promotes openness and transparency of the development process: unpolished changes go in separate branches (and WIP commits can be easily squashed, amended, etc); changes ready for review by maintainers go to the PR stage; changes considered ready are merged into master; and changes that have been on master for a while (hopefully tested by the most intrepid users who prefer not to wait for releases) are released with a stable (immutable) tag, downloadable as an archive, bundled with release notes, supported by the maintainers, etc.

Given this, I don't think we should word the top section based on the premise that master is a "release". If none of the options appeal to you, I agree, let's stick to what Keep a Changelog suggests.

[Xymph]

Alright, the "version x.y.x" header pattern makes "Unreleased version" a little more appealing than the others. If you agree, I'll update #85.

[waldyrious]

Agreed 👍

[Xymph]

+period

[waldyrious]

Fixed. Nice attention to detail, as always ;)

[Xymph]

Two minor textual fixes, otherwise this looks fine to me. 👍

[waldyrious]

@Xymph if everything looks good, please merge (squashing sounds sensible here, I suppose) at your leisure.

[Xymph]

I think a Changelog entry for the new file (under an "Added" heading) would make sense. To avoid a conflict, best review/merge #85 first.

[waldyrious]

Just to confirm, by the new file do you mean GOVERNANCE.md?

[Xymph]

Uhm, yes, what other new file was added in this "Create" PR? 😝

[waldyrious]

@Xymph rebased and updated CHANGELOG.md -- thanks for the prompt.

[Xymph]

-> [#83]

[waldyrious]

Argh. Good catch.

[Xymph]

Alright, your turn to wrap one up. 👍

[waldyrious]

Took me quite a while, but I can finally check this off my todo list! Thanks for the review.