Hi - TL:DR - The project should definitely use gitpubsub approach.
> On Mar 28, 2019, at 7:08 PM, Josh Fischer <[email protected]> wrote: > > How does everyone want to manage publishing the site? After looking at the > docs it seems there are 3 options. Being that we are using git, I would > thing that gitsubpub would be the path of least resistance?... But I can't > find much on how to create the jenkins job. Maybe this is listed somewhere > else in the documentation? Does anyone have other suggestions or ideas? > > Here is link to the guidelines -> > http://www.apache.org/dev/project-site.html. I copy and pasted some info > below on the different methods of website publishing for quick reference. > > > - Apache CMS, which provides a simple browser-based user interface for > editing, staging and publishing site content in Markdown, HTML or any other > source format for which support has been added. See the CMS reference > <https://www.apache.org/dev/cmsref> and adoption > <https://www.apache.org/dev/cmsadoption> for more details. The Apache > CMS uses svnpubsub as the underlying mechanism for publishing a site. While this was home grown in Apache and all the rage 7-8 years ago when I used this to port over OpenOffice.org with a reskin. This should not be used. Infra wants people to stop and there are occasional publishing issues. > - svnpubsub, which allows the static contents of a designated svn folder > (example <http://svn.apache.org/repos/asf/ant/site/ant/production/>) to > automatically published as the project web site at > http://project.apache.org/. The project team can use any site build > mechanism it wants as long as the above requirements are met. The CMS also uses svnpubsub. Not many new projects or podlings are using Subversion other than as required for releases. > - gitpubsub, which allows the static contents of a designated git > repository to be served as the website for a project. git based websites > are typically maintained in a asf-site branch to be published as > https://project.apache.org. They can be hosted from your primary project > repo. Typically these will be built as a jenkins job or a buildbot job. It > is recommended that you only have a single writer to the asf-site branch to > avoid potential conflicts. I’ve just revised the Incubator’s site build since we have a mix of svn legacy, current analysis and git static content. See https://github.com/apache/incubator and the README.md. This is a jBake site with two Jenkins build steps. This should be the approach. Two areas for further discussion. (1) Does the project wish to create documentation in a new repository - say apache/incubator-heron-site Or should the build use an asf-site branch in apache/incubator-heron which just keeps the deployed content. (2) Does the website Jenkins box already support the build requirements. >> Hugo --- Static site generator >> GulpJS --- Build tool for static assets >> Twitter Bootstrap --- Sass/CSS and JavaScript >> Documentation Setup >> Running the Heron documentation locally requires that you have the >> following installed: >> >> Make >> Node.js >> npm >> pip - install PyYAML>=3.12 >> Go (make sure that your GOPATH and GOROOT are set) What versions of the above and we can check with Infra through the [email protected] email. Regards, Dave >> >> On Fri, Mar 22, 2019 at 10:50 AM Josh Fischer <[email protected]> wrote: >> >>> I have some time free over the next week, I can look into fixing the >>> build.. However, I think we should figure out the repo situation first >> with >>> the submodule that is tied to the documentation. >>> >>> My responses are in *bold. * >>> >>> On Fri, Mar 22, 2019 at 12:26 PM Dave Fisher <[email protected]> >>> wrote: >>> >>>> Hi - >>>> >>>> Thanks for asking. This has been on my list to discuss with the Heron >>>> community. >>>> >>>> The website is seriously non-compliant. >>>> >>>>> On Mar 22, 2019, at 9:38 AM, Josh Fischer <[email protected]> >> wrote: >>>>> >>>>> Hey All, >>>>> >>>>> With the heavy lifting behind us on the Bazel upgrade, I think the >> next >>>>> task we should tackle is fixing the public docs. I have a few >> questions >>>>> about them. >>>>> >>>>> 1. Are they still to be served from GH pages? >>>> >>>> No. >>>> >>>>> 2. If not where do they need to live? >>>> >>>> It should be on Apache servers as heron.apache.org < >>>> http://heron.apache.org/> >>>> >>>> Many projects build through Jenkins. There are requirements for the >> site >>>> which are scanned. >>>> >>>> There is a page here (needs some updates) >>>> >>>> https://incubator.apache.org/guides/sites.html < >>>> https://incubator.apache.org/guides/sites.html> >>>> >>>> Some projects keep a separate GitHub repository for their website. >>>> >>> >>> * I would recommend that we move the docs out of this repo or at least >>> remove the submodule. Working within the submodule has been quite a >>> difficult task.* >>> >>>> >>>> There is a lot wrong with the current website. >>>> >>>> This page was put onto the Incubator website this week. (It’s been my >>>> “distraction” the last few weeks.) >>>> https://incubator.apache.org/clutch/heron.html#errata < >>>> https://incubator.apache.org/clutch/heron.html#errata> >>>> >>>> Check out that almost all ASF links, trademarks, disclaimer, and >>>> copyrights are not correct on a site scan that is periodically >> performed. >>>> >>>> https://whimsy.apache.org/pods/project/heron < >>>> https://whimsy.apache.org/pods/project/heron> >>>> >>>> >>>>> 3. If I remember correctly, some steps in the Makefile are >> currently >>>>> broken for building the static assets. Once those issues are >>> resolved >>>> is >>>>> there anything else we need to do to release new set of docs? >>>> >>>> Follow what I listed on 2. >>>> >>>> What technology is used to build assets currently? >>>> >>> >>> * It looks like is a mix of technologies.. The main one being Gulp. >>> For generating java docs Bazel is used to query targets. Generating >> python >>> docs pdoc is used. * >>> >>>> >>>>> 4. Does updating the docs require a vote? >>>> >>>> Not normally. The Podling can decide if you want to use RTC or CTR. >> Since >>>> everything is in version control I would lean to CTR! >>>> >>>> Regards, >>>> Dave >>>> >>>> >>>>> >>>>> - Josh >>>> >>>> >>> >>
