-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi all,
Our documentation is currently somewhat scattered and not very well organized. Before the 2.5 release, we tried to make an effort to get it more organized and updated, but didn't finish the job. We've had documentation split between 2 Confluence sites and the Apache CMS. Confluence provides a nice way to edit content, but doesn't show up at vcl.apache.org. The CMS is not as easy to edit, but does show up at vcl.apache.org. Now that we are switched over to Git, I'd like to explore the possibility of moving to GitHub pages for documentation (or at least using markdown and Jekyll). From my currently limited understanding, GitHub pages uses a markdown format, pages can be edited directly through the GitHub web site, and the markdown is compiled into HTML using Jekyll. What I'm not sure about yet is the integration between GitHub and ASF Git. On the ASF side, it sounds like we need two additional branches in Git - a name we come up with such as "documentation" that contains the markdown files, and "asf-site" that contains the Jekyll generated content. However, the "documentation" branch may need to be named something like "gh-pages" for GitHub integration purposes. The Apache Infrastructure team has started exploring this further [1][2] and creating some documentation, but haven't really written up anything yet. They do have a brief page explaining how the "asf-site" branch works. [3] There are a few other projects using Jekyll to generate content linked to from the [1] thread. Zookeeper has a good write up [4] on how to manually use Jekyll to generate the content and then commit that to Git. The OpenWhisk project has a response in the [1] thread explaining how they use Jenkins to automatically run Jekyll and push its output to their asf-site branch. What I'd really like to figure out is a way to use the GitHub web site to edit content, then issue a pull request to the the content committed to the ASF Git repo. Accepting the pull request would then commit the change to ASF Git which would trigger Jenkins to run Jekyll and commit the generated content to the asf-site branch. What are others thoughts on this? Thanks, Josh [1] https://lists.apache.org/thread.html/%[email protected]%3E [2] https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=75964385 [3] https://blogs.apache.org/infra/entry/git_based_websites_available [4] https://cwiki.apache.org/confluence/display/ZOOKEEPER/WebSiteSetup - -- - ------------------------------- Josh Thompson VCL Developer North Carolina State University my GPG/PGP key can be found at pgp.mit.edu All electronic mail messages in connection with State business which are sent to or received by this account are subject to the NC Public Records Law and may be disclosed to third parties. -----BEGIN PGP SIGNATURE----- iF0EARECAB0WIQRMIdRtWXideTZDK31X8tBw1209AwUCWw7xhAAKCRBX8tBw1209 A5jHAJ94Xe52HsPIYHrE7kAjfostcMOOcgCfZu2c7aSd9LLj5YCKZC9e8fosS5k= =/4Tb -----END PGP SIGNATURE-----
