Maintaining RELEASE-NOTES sucks
Open, Needs TriagePublic

Description

There's got to be a better way...

Reedy created this task.Dec 14 2015, 11:15 PM
Reedy updated the task description. (Show Details)
Reedy raised the priority of this task from to Needs Triage.
Reedy added a subscriber: Reedy.
Restricted Application added a project: Documentation. · View Herald TranscriptDec 14 2015, 11:15 PM
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald Transcript
demon added a subscriber: demon.Dec 14 2015, 11:16 PM
Isarra added a subscriber: Isarra.Dec 14 2015, 11:33 PM

Yes.

Issues:

  • People forget to even include release notes with their patches
  • Release notes are often not useful even if they do remember
  • Issues with only being able to add a small amount of information, can't do subsections, formatting, read mores very well
  • Edit conflicts out the wazoo changing one single file

Possible alternatives:

  • Keep it on-wiki and just dump a copy of that into gerrit periodically
  • Make some overly complicated thing where folks include separate json objects or something with their patches for each individual thing that get consolidated into a single list later
  • Come up with something that actually works, and hire a professional axe murderer to track down all the people who just plain forget
  • Give up
  • Keep it on-wiki and don't bother having a copy in git/gerrit at all, or perhaps have a placeholder RELEASE-NOTES that offers a link to its location on-wiki

Solves everything except "people forget to include notes with their patches" which we aren't going to solve via technical means anyway for the most part (although it would likely make it slightly worse since now there are 2 places to submit changes to instead of just 1, and you'd really want to just do it on wiki after the patch is merged)

ashley added a subscriber: ashley.Dec 14 2015, 11:44 PM
  • Edit conflicts out the wazoo changing one single file

Basically if and when you have a core patch that's more complicated than fixing a typo and/or tweaking code docs, you will stumble upon this issue. And it's annoying as hell.

Possible alternatives:

[...]

  • Give up

This is how I feel when having to deal with RELEASE-NOTES conflicts.

  • Keep it on-wiki and don't bother having a copy in git/gerrit at all, or perhaps have a placeholder RELEASE-NOTES that offers a link to its location on-wiki

+2. We develop a wiki software, we document it on a wiki (or try to, and then have these incomplete docs translated into a variety of languages that you've never heard of), so why not to ease everyone's life a tad bit and get rid of that plaintext file which is guaranteed to be always somewhat outdated anyway?

demon removed a subscriber: demon.Mar 9 2017, 8:53 PM