Better plan/docs for master-only, young projects

[bitprophet]

Problem

• Young projects with just a master branch & rapid iteration (like...this project) are often tempted to slam out arbitrary feature releases ("ehhh let's call this 0.3.0"), sometimes with bugfix releases in between, sometimes not - but almost always w/o really keeping release lines, numbers just go up.
• In this setup, the distinction between feature and bugfix releases can be blurred or nonexistent.
• That clashes with how Releases thinks about the world (namely, from a mature-project, multiple-release-line perspective.) Young projects must constantly remember to mark bugs as 'major', at the very least.

  Solutions

  1. Education only: document the phenomenon of pre-1.0 single-line release setups, remind that "mixed" releases will need to mark up the bugs and/or features as appropriate so they show up right.
  2. Logic update: pre-1.0 releases are considered to consume all issues listed since previous release. Maybe make this configurable for users who don't want it.
     • Counterpoint: this could confuse users since the behavior changes post 1.0, possibly "without warning."
  3. Do both: document it, make an opt-in (not opt-out) option saying "yes I want lazy pre-1.0 releases that suck up all issues".

Last feels best.

[keimlink]

I agree that the last option seems to be the best. Did you think of a setting to configure this?

[bitprophet]

Not really, offhand would probably be something like releases_lazy_betas (or alphas or prereleases or etc). Open to suggestions :)

[MinchinWeb]

What about if all non-released bugs are automatically rolled up in the next declared major release? In effect a major release would also serve as a minor release.

My use case is this: The current project I'm working on has a release once a month. I fix bugs as needed, and add features as requested. At the end of the month when I do my release, if it's just bugs, I'll call it a "minor" release; if it adds new features, I'll call it a "major" release.

So I propose that a changelog like this:

:release:`1.6.0 <2016-03-28>`
:bug:`3` some other bug
:feature:`2` shiny and new
:release:`1.5.1 <2016-02-28>`
:bug:`1` some bug
:release:`1.5.0 <2016-01-30>`
<pre-history>

Become a listing like this:

v 1.6.0 2016-03-28

• feature # 6 shiny and new
• bug # 3 some other bug

v 1.5.1 2016-02-28

• bug # 1: some bug

v 1.5.0 2016-01-30 ...

I think this would similarly solve the "Young Projects" problem above.

[bitprophet]

It sounds like you're describing option 2 from the description, @MinchinWeb :) with the important distinction that this ticket is about pre-1.0 releases which are thus less firmly subject to semantic versioning.

In my (& this project's) opinion, post-1.0, you would not want this behavior - you'd want to be using the major keyword explicitly instead.

That said, once implemented for pre-1.0 releases, it probably wouldn't be crazy hard to add a 2nd option saying "actually, screw semantic versioning, just vacuum up everything please, even post 1.0". Getting this implemented, period, is the trickier part (especially after the shenanigans I am undergoing for #45 which is overhauling a lot of internals).

[bitprophet]

Thought about this more from perspective of migrating Alabaster's changelog, which is very much the type this ticket describes. I arbitrarily banged out minor and/or bugfix releases; the bugfix ones were actual bugfix-only releases, but the minor ones frequently had both bug-like and feature-like issues in them.

But, since it wasn't a Releases changelog, that data's not even there unless I retroactively add it. So they're all just bare list-items which Releases treats as implicit bug-type issues.

This means that after reformatting the file to a Releases style setup, only the bugfix/tertiary releases appear, with anything attached to minor releases falling into the "next feature release" bucket. Clearly not great; only way to fix without a lot of annotation grunt-work is to implement this feature here.

---

Re: that: I think the only real way to do it is:

• Add an option enabling "linear mode" or some other appropriate term
  • Maybe, re: ticket OP, with another option toggling whether this behavior is limited to pre-1.0 releases or not.
  • But perhaps wait until somebody asks for it; it doesn't make a lot of sense to even use Releases if you want this simpler mode even past 1.0?
• When enabled, implicit/uncategorized line items would stop being classified as bugs, and instead lack any classification - probably both re: organizing and display.
  • This would, again, be closer to the conceptual model of "I'm not categorizing these at this point, they're all just issues". If one cares harder, one can manually annotate as usual, even interspersed with the implicit items if desired.
  • I still have to figure out the implementation/architectural details for how this would work, but pretty sure it's doable.

[bitprophet]

Had another minor thought, "maybe we should make the 'implicit line items are no longer displayed as [Bug]' behavior its own orthogonal setting?" - but I then realized it doesn't make much sense when this ticket's new behavior is not enabled. If those items are no longer considered bugs, but the changelog they're in cares about bug-vs-feature, how should they get classified? It's completely ambiguous, which is bad.

So for now I'm still going with a single option enabling both behaviors (rolling/linear release organization & not tagging unclassified items as bugs).

[bitprophet]

This works reasonably well now, there's a few tiny corner cases that might not work great (e.g. explicit issue-listing releases - not a widely used feature, likely even less so in tandem with this new feature) but those can wait.