Faster doc deployment is also a goal of this change. For older minor release, the documentation should updated if its incorrect or if the update is related to a bugfix. Every other change (like grammar/syntax, documenting existing features) should be up to the developer. If they want to spend the time, it's OK but not required.
On Wed, Apr 26, 2017 at 10:51 AM Josh Elser <josh.el...@gmail.com> wrote: > Thanks, Mike. I this helped solidify some of the confusion over the > ambiguity of how this would work as a developer that I had. > > Mike Walch wrote: > > I was thinking that each minor release (2.0, 2.1, etc) would have its own > > copy of the user manual markdown files in the master branch of the > > accumulo-website repo. We actually do this now in that a user manual > html > > file exists in master for each minor release. Currently, if you need to > > update documentation for 1.6, 1.7& 1.8, you need to update each minor > > release branch of Accumulo (I understand merging makes this easy), > generate > > 3 user manual html files, check them into master branch of > > accumulo-website. Developers simplify it by not immediately pushing user > > manual changes to the website and waiting for the next bug fix release > > which could be several months away. > > Is faster doc-deployment also a goal of this change? I'd agree that > we've been relatively "lazy" in making changes like you point out; but, > that's probably also in part trying to avoid the premature docs > publishing you mention below. > > Aside: HBase has recently automated their workflow so that when a change > to their "user manual" is committed, Jenkins will automatically > build+publish the generated HTML to their website. That might be > something we could consider looking at for either our current workflow > or this new workflow you're proposing. This hinged on some stuff from > infra (ability to commit changes safely from ASF jenkins), but I believe > this is all worked out now. > > > One potential issue that I do see with moving user manual source to the > > accumulo-website repo is that if you make a code change to the 2.0 branch > > for an upcoming 2.0.3 bug fix release, you might not want the 2.0 > > documentation updated for that change until 2.0.3 is released. > Developers > > will need to delay changing user manual until after release or add "since > > 2.0.3" to the new text in the user manual. However, new features should > > not added in bugfix releases so I don't think this will be as common as > > correcting bad documentation which needs to go out right of way. > > That's a good edge-case that we'll want/need to keep in mind. > > Since you've thought about this (at least more than I have), might you > be able to outline the high-level steps for our common docs cases in > this "new world" you're proposing? I think our doc additions typically > fall into the following buckets: new features, grammar/syntax fixes, > FAQ/HOWTO for common administrative actions in production. e.g. a new > feature would only land in one manual, whereas grammar/syntax would > (likely) land in all. I'm wondering if we can compose a simple workflow. > I also understand if you haven't thought that far ahead yet. >
