> On Apr 3, 2019, at 10:49 AM, Josh Fischer <[email protected]> wrote:
>
> Thanks for the info Dave. I have a couple of responses to your questions.
>
> (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.
>
> ** The site build is currently dependent on Bazel to generate Javadocs. I
> think we should just have a "asf-site" branch that is used within the
> current repo to serve static files from as it would require less moving
> parts. Not sure if that would cause any issues with the current setup
> though. I was asking Ning a similar question on how to set this up since I
> don't have write access to the repo yet.Hi -
Really? - Have you enabled 2FA on GitHub for your joshfischer1108 username?
I recommend that you get access fixed and then work on doing the build locally.
Once you have that we can work on the Jenkins build with triggers.
>
>
> (2) Does the website Jenkins box already support the build requirements.
>
> ** I will look into this.
Ask on the-asf.slack.com #asfinfra - tell them it is for a gitpubsub website
build.
Regards,
Dave
>
> On Wed, Apr 3, 2019 at 10:43 AM Dave Fisher <[email protected]> wrote:
>
>> 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
>>>>>>
>>>>>>
>>>>>
>>>>
>>
>>
