This is great to have a unified documentation place. On Thu, Jun 22, 2017 at 10:31 AM, Sijie Guo <[email protected]> wrote:
> FYI. I created a BP for this - > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=71012301 > > - Sijie > > On Mon, Jun 5, 2017 at 10:45 AM, Sijie Guo <[email protected]> wrote: > > > > > > > On Mon, Jun 5, 2017 at 10:20 AM, Enrico Olivelli <[email protected]> > > wrote: > > > >> Il lun 5 giu 2017, 17:56 Sijie Guo <[email protected]> ha scritto: > >> > >> > On Mon, Jun 5, 2017 at 3:07 AM, Flavio Junqueira <[email protected]> > >> wrote: > >> > > >> > > I don't have a super strong opinion here, but I'm not sure I > >> understand > >> > > the concern. The textile files are stored in the repo, so any doc > >> changes > >> > > should be reviewed and committed as any other code change, no? > Granted > >> > that > >> > > it is in the hands of a committer to push the changes to the web > site, > >> > > which isn't very friendly. > >> > > > > Merging the website source files to bookkeeper repo is a simple step. But > > moving the website sources files to bookkeeper repo will break the build > > procedure (this is how CMS is working), so we need to move the build > > procedure along with moving the source files. > > > > > >> > > > >> > > >> > Two concerns: > >> > > >> > - Website is in the CMS repo, not in bookkeeper's source repo. The > >> review > >> > process are different between these two repo and a change to website, > >> docs > >> > and source code is fragmented, which makes reviewing a bit difficult. > >> > - Changes to bookkeeper docs require a manual commit to CMS repo to > >> trigger > >> > building the website. It isn't friendly to committers. > >> > > >> > > >> > > > >> > > In the case we move out of CMS, where would the site be hosted? > >> > > > >> > > >> > There are three questions behind this: > >> > > >> > 1) Where do we host the source files for the website and docs? > >> > 2) How do we generate the static content? > >> > 3) Where do we host the generated content? > >> > > >> > My comments: > >> > > >> > 1) I'd like the source files of website and docs to be along with > source > >> > codes. If a change requires modifying docs and website, it is very > >> > convenient to review all of them in one same pull request. At the > >> minimum, > >> > I'd like the source files of website and docs are in the same repo. > >> > 2) There are tons of static content generator, for example, Jekyll, > >> Hugo. I > >> > want one is friendly to github pages, so developers/commiters can > easily > >> > use github pages to validate the changes and also show the result when > >> > asking for reviews. > >> > 3) The host generated content can be on any git repo under asf-site > >> branch, > >> > using gitpubsub - > >> > https://blogs.apache.org/infra/entry/git_based_websites_available > >> > >> > >> As this post is saying it would be an easy step at least to switch to > git, > >> maybe we can just create a directory website and cut and paste the > actual > >> content. > >> We can lose the history, or maybe we could also keep the while history, > >> but > >> in all of my migrations from svn to git I always created a new repo and > >> not > >> merged a svn with a git one. Maybe it would be possible as well. > >> > >> I would like to at least make this step so that we will have all in git > >> > >> > >> > > >> > > >> > - Sijie > >> > > >> > > >> > > > >> > > -Flavio > >> > > > >> > > > On 03 Jun 2017, at 21:42, Enrico Olivelli <[email protected]> > >> wrote: > >> > > > > >> > > > Our site is written using Textile, I found this > >> > > > https://github.com/jekyll/jekyll-textile-converter maybe the > >> switch to > >> > > > Jekyll will be easy > >> > > > > >> > > > The other problem will be to switch the cms, maybe just a request > to > >> > > > infra to switch to github pages will be enough > >> > > > > >> > > > Enrico > >> > > > > >> > > > 2017-06-03 19:15 GMT+02:00 Sijie Guo <[email protected]>: > >> > > >> I don't think there is any enforcements from Apache INFRA side. > You > >> > can > >> > > use > >> > > >> any technology for hosting website and documentation. I do see a > >> lot > >> > of > >> > > >> projects using Jekyll-like solutions for the website, where they > >> > > typically > >> > > >> have a separate XXX-site git repo and use gitpubsub (which is > just > >> a > >> > > simply > >> > > >> git push) for publishing the content. > >> > > >> > >> > > >> For DL, originally the website was generated by internally tool > >> called > >> > > >> DocBird. When we open sourced DL, we push the generated static > >> content > >> > > to > >> > > >> gh-pages and uses github pages for hosting the content. After we > >> moved > >> > > to > >> > > >> incubator, we changed to use Jekyll to generate the static > content > >> and > >> > > add > >> > > >> the generated content on asf-site branch. > >> > > >> > >> > > >> For me, I don't care what technologies we are using. I'd like a > >> > simpler > >> > > >> workflow, same/similar as the source code workflow and every > >> changes > >> > > should > >> > > >> be under same/similar review process. Any git-based, > >> github-friendly > >> > > >> solution would be preferred here. If we agree on moving, we > should > >> > call > >> > > for > >> > > >> volunteers to help with this. > >> > > >> > >> > > >> - Sijie > >> > > >> > >> > > >> On Sat, Jun 3, 2017 at 4:24 AM, Enrico Olivelli < > >> [email protected]> > >> > > wrote: > >> > > >> > >> > > >>> It has been some time since you made this proposal, on some > >> ticket. > >> > > >>> At the moment I did not make any concrete proposal because I > >> wanted > >> > to > >> > > >>> study how to make the conversion. > >> > > >>> I am in favour of switching to a more popular sokution like > jekyll > >> > and > >> > > >>> maybe markdown language > >> > > >>> Using git will be good as well. It will be more integrated. > >> > > >>> > >> > > >>> I am not an expert I think we need some volunteer toto carry on > >> the > >> > > >>> migration. > >> > > >>> > >> > > >>> On the infra side it would be good to listen to experiences from > >> > other > >> > > >>> apache projects. On new DL site what technology are you using? > >> > > >>> Kafka website has been restyled some month ago, maybe we can > take > >> a > >> > > look > >> > > >>> > >> > > >>> -- Enrico > >> > > >>> > >> > > >>> Il sab 3 giu 2017, 02:21 Sijie Guo <[email protected]> ha > >> scritto: > >> > > >>> > >> > > >>>> I'd like to raise another discussion about moving bookkeeper > >> website > >> > > from > >> > > >>>> CMS to other static generators (e.g. Jekyll, Hugo). > >> > > >>>> > >> > > >>>> BookKeeper uses Apache CMS for generating the documentation and > >> > > website > >> > > >>>> [1]. The website source code is hosted at a svn repo, which now > >> > > becomes > >> > > >>>> obsolete from > >> > > >>>> our current review/workflow. I also heard committers > complaining > >> > about > >> > > >>> the > >> > > >>>> steps to get a change out. > >> > > >>>> > >> > > >>>> I think it is the time to also think of moving the website away > >> from > >> > > CMS > >> > > >>> to > >> > > >>>> a more Github friendly solution. > >> > > >>>> > >> > > >>>> We should consider follows for the new solution: > >> > > >>>> > >> > > >>>> - have similar review flow as the main source code (github pull > >> > > >>> requests). > >> > > >>>> - developers can easy to folk and run/validate their changes > >> > locally, > >> > > and > >> > > >>>> maybe also easier for the other reviews to verify. > >> > > >>>> > >> > > >>>> Any thoughts? > >> > > >>>> > >> > > >>>> [1] : > >> > > >>>> > >> > > >>>> https://cwiki.apache.org/confluence/display/BOOKKEEPER/ > >> > > >>> Building+the+website+and+documentation > >> > > >>>> > >> > > >>> -- > >> > > >>> > >> > > >>> > >> > > >>> -- Enrico Olivelli > >> > > >>> > >> > > > >> > > > >> > > >> -- > >> > >> > >> -- Enrico Olivelli > >> > > > > >
