+1 I’m happy we can finally move on with this. And agree with Hoss that docs must be expected with code, or else the released git version will not contain the correct refguide. We cannot rely on releasing the refguide weeks after the code anymore, and we can’t hold up the release process and do tons of re-spins for simple adoc changes.
But that also makes it important that any committer is given good tools to make sure her edits look good. I hope Asciidoc is more standardised than Markdown, else your choice of tooling may ultimately decide whether your edits look good or bad. Would it be possible to add a JIRA bot that tries to apply the latest SOLR-XXXX.patch (like the Hadoop QA bot does, see https://issues.apache.org/jira/secure/ViewProfile.jspa?name=hadoopqa <https://issues.apache.org/jira/secure/ViewProfile.jspa?name=hadoopqa>) and also, if the patch contains .adoc changes, verify and provide a preview of those changes right there in JIRA? -- Jan Høydahl, search solution architect Cominvent AS - www.cominvent.com > 14. mar. 2017 kl. 00.50 skrev Chris Hostetter <[email protected]>: > > > : *) should there be LICENCE on the Github repo if you want people to > : play/experiment/contribute ideas? > > I'm not sure that's really neccessary at this point -- so far all of the > contributions have been from existing committers, and we (probably?) don't > want to take on any (new) significant contributions from general users > until we get it imported into the lucene-solr.git repo? > > : *) This part is future, right? "Custom Java tooling will be used to > : process the .adoc file metadata to build up navigation data files" I > : can't find it in the repo, but maybe I am confused. > > no -- it already exists. See solr-ref-guide/build.xml and > solr-ref-guide/tools. > > That "tools" code is "long life" code that will exist for managing the > ref-guide even after the migration ... possibly some where in dev-tools i > would imagine? > > (stuff under "confluence-export/conversion-tools" will be thrown away) > > > : *) Because "How will we provide search? Recommend probably indexing > : generated HTML pages. Could use bin/post from Solr to recurse over the > : HTML files and index them. In this case, we will need to figure out > : where to host Solr." - this is slightly embarrassing.... > > that would be a nice to have, but since we already rely on third parties > (search-lucene.com & find.searchhub.org and ) to provide solr indexes of > our website, relying on them to search the ref guide shouldn't be a deal > breaker / blocker) > > : > 2) We need to decide on our policy for branches. I recall there was > : > valid concern about the process around this when I first proposed the > : > change. I'd like to iron that out as soon as we can since that will be > : > a key part of our new process. > : > > : > From our discussion last summer, there are 2 potential approaches: > : > > : > a) Make all changes in 'master' (trunk) and backport to branches for > : > releasing the content. We'd need to merge "backward" into upcoming > : > release branch. > : > b) 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. > > I personally think "#A" 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. > * etc... > > > : > I appreciate in advance your feedback. As a reminder, you can see the > : > demo site/PDF and the project repo at: > : > > : > http://people.apache.org/~ctargett/RefGuidePOC/ > : > https://github.com/ctargett/refguide-asciidoc-poc > > > -Hoss > http://www.lucidworks.com/ > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] >
