Pull requests for docs is a great plus so more people can contribute. The online version-specific docs can then have a link below each page encouraging people to contribute through PR to version-branch or by comment system.
An issue with only maintaining the next-release branch is that docs on master will get out of date. But that is perhaps not a problem since there will not be an online HTML version of master? Anyway, with a merge-forward strategy, we could e.g. merge to master after each point release on 6.x, to avoid the gap becoming too large over time. -- Jan Høydahl, search solution architect Cominvent AS - www.cominvent.com > 19. aug. 2016 kl. 19.48 skrev Tomás Fernández Löbbe <tomasflo...@gmail.com>: > > Thanks for taking time for looking at these options Casandra. I specially > agree with the third of the painful points you mentioned, the fact that we > can't maintain online documentation for different versions. I like that we > have a released PDF version for every minor version, but 99.9% of the time > I'm online and I just want to go to the online version and browse the HTML > docs, it's a pain that I can't just choose my version there. > I also agree 100% with Doug's point, that we should make sure that links to > the current documentation pages are correctly forwarded to the new docs. > Accepting pull requests would also be nice, many of the comments in > Confluence are "there is a typo in…" or "X section is missing parameter Y", I > bet many of those comments will become PRs if we offered the option (don't > know if this can be handled without Jira) > > About branching and merging, we currently write docs for the next version > (minor usually), very few things are written for master only, and they > currently live in a separate Confluence area that's not released. One option > would be keep doing this, which will prevent many merges (at the cost of > making it more difficult to release docs for new major versions). > > in general, +1 for the idea. > > Tomás > > On Fri, Aug 19, 2016 at 10:23 AM, Chris Hostetter <hossman_luc...@fucit.org > <mailto:hossman_luc...@fucit.org>> wrote: > > : I am not against having multiple documentation branches -- I am *for* > : that. I am against emulating our current source code practice of needing > : to commit twice (two branches) for most things. I think that should be the > : exception, not the rule. Only during a new dot-zero release would we be > : compelled to merge forward the changes from the previous branch. > > To be very clear, my point was that by moving out of confluence and to an > asciidoc based system kept in git, we know have the *choice* to > maintain/backport documentation for multiple versions, and an easy way to > backport changes. > > This is not even a viable *option* for us to consider with confluence. > > if/how/when to backport/forward-port documentation is a policy question we > can decide at a later date -- the hypothetical example i gave was just one > that assumed we'd want to keep docs in sync with code -- The main take > away was to point out that we can now make that decision for ourselves if > we migrat out of confluence. > > > > -Hoss > http://www.lucidworks.com/ <http://www.lucidworks.com/> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org > <mailto:dev-unsubscr...@lucene.apache.org> > For additional commands, e-mail: dev-h...@lucene.apache.org > <mailto:dev-h...@lucene.apache.org> > >
