[jira] [Commented] (SOLR-10294) Decide branching strategy for Ref Guide

["Cassandra Targett (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-10294?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15926849#comment-15926849 ] 

Cassandra Targett commented on SOLR-10294:
------------------------------------------

From [~hossman] (devs@lucene email 12 Mar 2017, Re: Moving the Ref Guide: Progress Update & Next Steps):

{quote}
I personally think "#1" is the only sane way to manage the ref guide.

I think we should do everything we can to move towards ref-guide edits
being committed & managed exactly the same as source code edits -- ideally
in the exact same commits, to the exact same repo. So that if you are
adding/fixing a Foo feature, you have a single commit to master that edits
Foo.java and Foo.adoc (just in diff directories).  When you want to
backport that feature to branch 6x, you backport the whole commit.

(we would never consider committing fixes/improvements to code, and then
leaving javadoc corrections about those code changes until just before
release weeks later -- we shouldn't approach writing user docs that way
either.)

Having this branching model, and getting use to this model of
committing/backporting doc changes at the exact same time we
commit/backport code, is the only way we can ever hope to move forward
with any of the really powerful things using adoc files (and a command
line ref-guide build system) can support:

 * building the ref guide & checking broken links as part of our
precommit/smoketest build targets.
 * writing automated "tests" of our documentation (ex: assert every
collections API 'command' has a coresponding page/section) that can be run
by jenkins.
{quote}

> Decide branching strategy for Ref Guide
> ---------------------------------------
>
>                 Key: SOLR-10294
>                 URL: https://issues.apache.org/jira/browse/SOLR-10294
>             Project: Solr
>          Issue Type: Sub-task
>      Security Level: Public(Default Security Level. Issues are Public) 
>          Components: documentation
>            Reporter: Cassandra Targett
>
> Since one of the reasons to move off Confluence is to provide online docs for specific versions of Solr, we should agree up front how we'll manage working with the branches.
> There are two general proposals on the table so far:
> #  Make all changes in 'master' (trunk) and backport to branches for
> releasing the content. We'd need to merge "backward" into upcoming
> release branch.
> # Make all changes in branch_6x (or branch_7x, etc.) and only move
> things to master when they are only applicable to unreleased next
> major version. We'd merge 6x "forward" when it's time for next major
> version.
> Some discussion on this started in the mailing list, so I'll copy the feedback received so far on this as comments to this issue.



--
This message was sent by Atlassian JIRA
(v6.3.15#6346)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org