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 >> > >
