Hi All, Our current status with regards to the TomEE website is we have one foot in each world, old and new. The high-level history is more or less this:
- 2006-2012 we used Confluence as the "source" and rendered that to html via a plugin maintained by one brave ASF individual, Pier Paolo Fumagalli. - 2012-2016 the ASF discontinued use of confluence like this and everyone moved to the Apache CMS, maintained by one brave ASF individual, Joe Schaefer. Each project's code was exported as-is into svn. Joe and I did a bunch of work to get TomEE setup and was one of the first to use this system. It was written in perl and basically invented Pull Requests before github and wasn't a bad solution. We succeeded in fully migrating away from Confluence. We didn't succeed in fully migrating content from Confluence markup to Markdown. - 2016 the ASF discontinued Apache CMS after Joe left. Romain did a lot of great work to get JBake up and running. JBake is written in Java and can easily be maintained by us, whereas anything else we've had could not. This was done "on top" of the old site, with all the old content still there and decaying. The old content is still generated by the Apache CMS. We didn't succeeded in fully migrating away from Apache CMS. We now have duplicate content that confuses us all. The JBake work is technically the closest to success I think we've ever seen. The state of our content, however, is in need of significant love. Here are some issues I think have caused repeat failure in all our documentation attempts: - Having just one "source" where documentation lived. - Mixing general project docs and technical docs. When the topic of moving the docs into the main TomEE repo is raised, someone rightfully says, "what about the general project docs like contribution-tips?" When the topic of trying to version the docs outside TomEE, someone says "that's a huge maintenance nightmare, maybe we can put some kind of 'since version 1.2.3' on sections of the docs?" In the end I think all forms of "one big pile of docs" doesn't work even if that's git, svn, or confluence. Our current status of "two big piles of docs", but with no clear line between them, works even less. Here's what I've tried to do and this is a work in progress: - Merge old and new docs into one "pile" again - Split out the docs that could be versioned and put them into the main TomEE repo - Update our JBake setup so it uses jgit to select content from maintained TomEE branches & tags The Merge: - old: https://github.com/apache/tomee-site/tree/trunk/content - new: https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content - merged: https://github.com/dblevins/tomee-site-generator/tree/master/src/main/jbake/content The Split: Anything that could reasonably be tied to a release has been moved to "master" of the main TomEE repo: - https://github.com/dblevins/tomee/tree/tomee-8.0.x-docs/docs The JBake Improvements: We just grab from any number of repos and make one directory tree from them before we pass it to JBake. This gives us these URLs (not live of course, so don't try to click them): - http://tomee.apache.org/tomee-7.0/docs/ - http://tomee.apache.org/tomee-7.0/examples/ - http://tomee.apache.org/tomee-7.1/docs/ - http://tomee.apache.org/tomee-7.1/examples/ - http://tomee.apache.org/tomee-8.0/docs/ - http://tomee.apache.org/tomee-8.0/examples/ - http://tomee.apache.org/latest/docs/ - http://tomee.apache.org/latest/examples/ - http://tomee.apache.org/master/docs/ - http://tomee.apache.org/master/examples/ The intent being 7.0 is feed from the latest tag, which is currently 7.0.5. When 7.0.6 is released, all "/tomee-7.0/" urls will be rebuilt from the 7.0.6 tag. Same for 7.1, 8.0, etc. The "latest" allows for a permalink and would point to what we consider to be the best, likely the tomee-8.0.0-M1 tag. The "master" is so we can update and publish documentation in conversations with users and get their feedback prior to release. This is all early-stage, still prototype, work in progress. Help is incredibly welcome. You can try out what's there so far, like so: $ git clone g...@github.com:dblevins/tomee-site-generator.git $ cd tomee-site-generator $ mvn clean compile -Djbake.http=true Once that is done, you can open your browser to any of these urls: - http://localhost:8080/docs.html - http://localhost:8080/master/examples/mp-metrics-counted.html - http://localhost:8080/latest/examples/cdi-basic.html - http://localhost:8080/tomee-8.0/examples/cdi-basic.html - http://localhost:8080/tomee-8.0/docs/configuring-javamail.html -- David Blevins http://twitter.com/dblevins http://www.tomitribe.com
