: *) 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: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
