You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jena.apache.org by Roy Lenferink <rl...@apache.org> on 2020/02/15 13:28:11 UTC
[DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Hi Jena community,
I noticed Jena is still serving its site from SVN with help of the Apache CMS. At the Apache Celix
project we decided to move away from the CMS and move towards git for serving our website [1].
This because the CMS was introduced in 2010 and is currently not accepting any new projects. With
the move to Hugo we're sure that we still can update the site when the ASF CMS will be
decommissioned.
The master branch contains the actual website sources whereas the generated website is served
from the asf-site branch. Hugo is being used as static website generator. Content is written in
Markdown.
I had a look at Jena its site and it was quite easy to migrate Jena its site to use Hugo as well. An
example of Hugo its output is (for demo purposes only) available on [2]. These are the existing
markdown files with a slightly changed header.
Moving to git can enlarge the visibility of how projects are functioning. Next to that, new contributors
can simply create a pull request against the website repository if they find anything they want to
improve. I've updated the 'Improve this page' to 'Edit this page' which will open the GitHub webpage
to edit the currently viewed page (currently returning a 404 because the apache/jena-site repository
does not exist).
If the community is interested in this move what I propose:
- Someone from the PMC to request a new git repository for the website (e.g. jena-site) via [4]
- Me creating the pull request from the repository I am temporarily using for the website contents [5]
to the official jena-site repository
- Create a Jenkins job to automatically build the site after changes happen on the master branch.
- When the pull request is reviewed and merged ask INFRA to move over from the current svnpubsub
to the gitpubsub approach and remove Jena from the Apache CMS.
Next to that Jena is also providing javadocs on its site. My proposal for this is to serve them from a
separate branch (e.g. release-docs). This way people who only want to clone the site can clone the
the master branch using --single-branch and will not be bothered with cloning all the javadocs.
All the URLs are still the same so the SEO score is not influenced in any way.
I'd like to hear everyone's opinion on this :)
Best regards,
Roy
[1] https://github.com/apache/celix-site
[2] http://jena.roylenferink.nl/
[3] http://celix.apache.org/contributing/releasing.html
[4] https://gitbox.apache.org/setup/newrepo.html
[5] https://github.com/rlenferink/jena-site
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Roy Lenferink <rl...@apache.org>.
On 2020/02/19 23:06:31, Andy Seaborne <an...@apache.org> wrote:
>
>
> On 19/02/2020 19:06, Andy Seaborne wrote:
> > I am finding some conversion issues around boxes and <code>
> >
> > https://jena.apache.org/tutorials/rdf_api.html#ch-Statements
> > vs
> > http://jena.roylenferink.nl/tutorials/rdf_api.html#ch-Statements
> >
> > The example is doubly boxed and the fint size keeps jumping.
> >
> > Yes, the Jena site markup is a bit yuk - it is a conversion itself - but
> > we have the content we have.
>
> I've cleared up some problems - on staging now.
>
Pulling in the latest changes from svn seemed to have solved the problem. The 'old' page shows
it as a <blockquote> element as well. I don't know if this is necessary because the 'new' page drops
that element. This should be fixable but IMO loosing the blockquote isn't that much of a problem.
The page is still pretty readable (updated the demo page as well so can have a look yourself :) ).
> >
> > There are changes around whitespace and tables. sometimes better,
> > sometimes not. And I have seen an odd "Title" change where ":" becomes "-"
> >
The titles have been restored to there original ones. Good catch!
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Andy Seaborne <an...@apache.org>.
On 19/02/2020 19:06, Andy Seaborne wrote:
> I am finding some conversion issues around boxes and <code>
>
> https://jena.apache.org/tutorials/rdf_api.html#ch-Statements
> vs
> http://jena.roylenferink.nl/tutorials/rdf_api.html#ch-Statements
>
> The example is doubly boxed and the fint size keeps jumping.
>
> Yes, the Jena site markup is a bit yuk - it is a conversion itself - but
> we have the content we have.
I've cleared up some problems - on staging now.
>
> There are changes around whitespace and tables. sometimes better,
> sometimes not. And I have seen an odd "Title" change where ":" becomes "-"
>
> Andy
>
> On 15/02/2020 13:28, Roy Lenferink wrote:
>> Hi Jena community,
>>
>> I noticed Jena is still serving its site from SVN with help of the
>> Apache CMS. At the Apache Celix
>> project we decided to move away from the CMS and move towards git for
>> serving our website [1].
>> This because the CMS was introduced in 2010 and is currently not
>> accepting any new projects. With
>> the move to Hugo we're sure that we still can update the site when the
>> ASF CMS will be
>> decommissioned.
>>
>> The master branch contains the actual website sources whereas the
>> generated website is served
>> from the asf-site branch. Hugo is being used as static website
>> generator. Content is written in
>> Markdown.
>>
>> I had a look at Jena its site and it was quite easy to migrate Jena
>> its site to use Hugo as well. An
>> example of Hugo its output is (for demo purposes only) available on
>> [2]. These are the existing
>> markdown files with a slightly changed header.
>>
>> Moving to git can enlarge the visibility of how projects are
>> functioning. Next to that, new contributors
>> can simply create a pull request against the website repository if
>> they find anything they want to
>> improve. I've updated the 'Improve this page' to 'Edit this page'
>> which will open the GitHub webpage
>> to edit the currently viewed page (currently returning a 404 because
>> the apache/jena-site repository
>> does not exist).
>>
>> If the community is interested in this move what I propose:
>> - Someone from the PMC to request a new git repository for the website
>> (e.g. jena-site) via [4]
>> - Me creating the pull request from the repository I am temporarily
>> using for the website contents [5]
>> to the official jena-site repository
>> - Create a Jenkins job to automatically build the site after changes
>> happen on the master branch.
>> - When the pull request is reviewed and merged ask INFRA to move over
>> from the current svnpubsub
>> to the gitpubsub approach and remove Jena from the Apache CMS.
>>
>> Next to that Jena is also providing javadocs on its site. My proposal
>> for this is to serve them from a
>> separate branch (e.g. release-docs). This way people who only want to
>> clone the site can clone the
>> the master branch using --single-branch and will not be bothered with
>> cloning all the javadocs.
>>
>> All the URLs are still the same so the SEO score is not influenced in
>> any way.
>>
>> I'd like to hear everyone's opinion on this :)
>>
>> Best regards,
>> Roy
>>
>> [1] https://github.com/apache/celix-site
>> [2] http://jena.roylenferink.nl/
>> [3] http://celix.apache.org/contributing/releasing.html
>> [4] https://gitbox.apache.org/setup/newrepo.html
>> [5] https://github.com/rlenferink/jena-site
>>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Andy Seaborne <an...@apache.org>.
I am finding some conversion issues around boxes and <code>
https://jena.apache.org/tutorials/rdf_api.html#ch-Statements
vs
http://jena.roylenferink.nl/tutorials/rdf_api.html#ch-Statements
The example is doubly boxed and the fint size keeps jumping.
Yes, the Jena site markup is a bit yuk - it is a conversion itself - but
we have the content we have.
There are changes around whitespace and tables. sometimes better,
sometimes not. And I have seen an odd "Title" change where ":" becomes "-"
Andy
On 15/02/2020 13:28, Roy Lenferink wrote:
> Hi Jena community,
>
> I noticed Jena is still serving its site from SVN with help of the Apache CMS. At the Apache Celix
> project we decided to move away from the CMS and move towards git for serving our website [1].
> This because the CMS was introduced in 2010 and is currently not accepting any new projects. With
> the move to Hugo we're sure that we still can update the site when the ASF CMS will be
> decommissioned.
>
> The master branch contains the actual website sources whereas the generated website is served
> from the asf-site branch. Hugo is being used as static website generator. Content is written in
> Markdown.
>
> I had a look at Jena its site and it was quite easy to migrate Jena its site to use Hugo as well. An
> example of Hugo its output is (for demo purposes only) available on [2]. These are the existing
> markdown files with a slightly changed header.
>
> Moving to git can enlarge the visibility of how projects are functioning. Next to that, new contributors
> can simply create a pull request against the website repository if they find anything they want to
> improve. I've updated the 'Improve this page' to 'Edit this page' which will open the GitHub webpage
> to edit the currently viewed page (currently returning a 404 because the apache/jena-site repository
> does not exist).
>
> If the community is interested in this move what I propose:
> - Someone from the PMC to request a new git repository for the website (e.g. jena-site) via [4]
> - Me creating the pull request from the repository I am temporarily using for the website contents [5]
> to the official jena-site repository
> - Create a Jenkins job to automatically build the site after changes happen on the master branch.
> - When the pull request is reviewed and merged ask INFRA to move over from the current svnpubsub
> to the gitpubsub approach and remove Jena from the Apache CMS.
>
> Next to that Jena is also providing javadocs on its site. My proposal for this is to serve them from a
> separate branch (e.g. release-docs). This way people who only want to clone the site can clone the
> the master branch using --single-branch and will not be bothered with cloning all the javadocs.
>
> All the URLs are still the same so the SEO score is not influenced in any way.
>
> I'd like to hear everyone's opinion on this :)
>
> Best regards,
> Roy
>
> [1] https://github.com/apache/celix-site
> [2] http://jena.roylenferink.nl/
> [3] http://celix.apache.org/contributing/releasing.html
> [4] https://gitbox.apache.org/setup/newrepo.html
> [5] https://github.com/rlenferink/jena-site
>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Andy Seaborne <an...@apache.org>.
On 21/02/2020 18:59, Roy Lenferink wrote:
>> 3/ There is a "jena-site:release-docs" branch for javadoc
>> Let's say this has /javadoc
>
> If we have the following configured in the gitwcsub.cfg (INFRA stuff)
> /www/jena.apache.org: $gitbox/jena-site
> This means that the 'asf-site' contains a 'content' folder with the actual site content.
>
> /www/jena.apache.org/content/documentation/javadoc: $gitbox/jena-site:release-docs
> This means that everything from the root of the release-docs branch will be served on
> jena.apache.org/documentation/javadoc
Excellent. Even better.
I would name it "javadoc" though. The name "released-docs" covers the
all the documentation to my mind.
To be clear : I think you are saying that the root of the :javadoc
branch will be like:
arq/ extras/ fuseki2-main/ jdbc/ permissions/ shacl/
tdb2/ elephas/ fuseki2/ geosparql/ jena/ rdfconnection/
tdb/ text/ index.md
not
javadoc/
>
> The release-docs branch will contain an exact copy of the following:
> https://svn.apache.org/repos/infra/websites/production/jena/content/documentation/javadoc/
>
...
>>
>> 6/ There is no "jena.staging.apache.org". It is replaced by people
>> running "hugo" locally to get "/target/content" : "hugo server" puts it
>> on http://localhost:1313
>
> The staging domain is indeed gone. An alternative could be to use Netlify (netlify has free plans for
> OSS projects). Netlify will build pull requests and comment with a link to the preview. Celix has this
> enabled as well. See this pull request as example: https://github.com/apache/celix-site/pull/7
>
> (of course cgi scripts are not working but this is expected behavior)
>
> But maybe with the new site build solution that INFRA is currently working on the staging domain
> will be re-introduced as well ;) This is something we probably will find out in a couple of weeks.
So the only thing outstanding is the "Improve this page" link becoming
"Edit this page".
(as a bare minimum, if that needs any later tweaking, it could be a link
to text in getting_involved/__index.md explaining how to git-clone and
PR. Not as good, but it de-risks that element).
Sorry for the the details questions :-) but to be as smooth as possible,
details matter!
FYI: My time on Jena is a bit bursty at the moment.
Andy
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Roy Lenferink <rl...@apache.org>.
On 2020/02/21 18:24:08, Andy Seaborne <an...@apache.org> wrote:
> Is the following description correct and complete?
>
> 1/ We have repo "jena-site"
>
> I prefer the website to be separate from the code and not in the
> source-release so we are free to publish the site at anytime.
This is indeed my suggestion as well because sites most probably need to be updated separate from
releases.
>
> 2/ We have a branch of the "jena-site:asf-site" that is the published
> webside
>
> 3/ There is a "jena-site:release-docs" branch for javadoc
> Let's say this has /javadoc
If we have the following configured in the gitwcsub.cfg (INFRA stuff)
/www/jena.apache.org: $gitbox/jena-site
This means that the 'asf-site' contains a 'content' folder with the actual site content.
/www/jena.apache.org/content/documentation/javadoc: $gitbox/jena-site:release-docs
This means that everything from the root of the release-docs branch will be served on
jena.apache.org/documentation/javadoc
The release-docs branch will contain an exact copy of the following:
https://svn.apache.org/repos/infra/websites/production/jena/content/documentation/javadoc/
>
> 4/ The site is built by a Jenkins job at ASF. The job is triggered manually.
> e.g.
> https://builds.apache.org/job/celix-site/
>
> It is restricted to run on 'git-websites'
>
> 5/ It runs a shell script - see the one for Celix -
>
> In essence the job does:
>
> * pull master
> * run Hugo to get the pages in /temp-??/output
> * switch to 'asf-site'
> * copy /temp-??/output to /content
> /content/ is the site root.
> * <javadoc>
> * commit
> * push -u
>
> Is there an example of a project that does javadoc?
> Looks to me like at <javadoc>
>
> git co release-docs
> cp -r /javadoc /content/documentation/
>
Copying the release-docs to the asf-site branch is not even necessary. The config above (the INFRA
part) defines that on the production machine content is being served from 2 branches. It _is_
possible to copy it to the asf-site branch and then serve everything from the asf-site, but that is just
an additional step which I wouldn't do personally (we already have all the documentation available
on the release-docs branch, no need to copy it over. Just let INFRA handle the merging of the actual
content.
> It emails rlenferink@apache.org -- no need to change that :-)
Let's keep that :)
>
> We need to modify the script because it does not handle separate javadoc.
>
> 6/ There is no "jena.staging.apache.org". It is replaced by people
> running "hugo" locally to get "/target/content" : "hugo server" puts it
> on http://localhost:1313
The staging domain is indeed gone. An alternative could be to use Netlify (netlify has free plans for
OSS projects). Netlify will build pull requests and comment with a link to the preview. Celix has this
enabled as well. See this pull request as example: https://github.com/apache/celix-site/pull/7
(of course cgi scripts are not working but this is expected behavior)
But maybe with the new site build solution that INFRA is currently working on the staging domain
will be re-introduced as well ;) This is something we probably will find out in a couple of weeks.
>
> Andy
>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Andy Seaborne <an...@apache.org>.
Is the following description correct and complete?
1/ We have repo "jena-site"
I prefer the website to be separate from the code and not in the
source-release so we are free to publish the site at anytime.
2/ We have a branch of the "jena-site:asf-site" that is the published
webside
3/ There is a "jena-site:release-docs" branch for javadoc
Let's say this has /javadoc
4/ The site is built by a Jenkins job at ASF. The job is triggered manually.
e.g.
https://builds.apache.org/job/celix-site/
It is restricted to run on 'git-websites'
5/ It runs a shell script - see the one for Celix -
In essence the job does:
* pull master
* run Hugo to get the pages in /temp-??/output
* switch to 'asf-site'
* copy /temp-??/output to /content
/content/ is the site root.
* <javadoc>
* commit
* push -u
Is there an example of a project that does javadoc?
Looks to me like at <javadoc>
git co release-docs
cp -r /javadoc /content/documentation/
It emails rlenferink@apache.org -- no need to change that :-)
We need to modify the script because it does not handle separate javadoc.
6/ There is no "jena.staging.apache.org". It is replaced by people
running "hugo" locally to get "/target/content" : "hugo server" puts it
on http://localhost:1313
Andy
[A]
https://www.apache.org/dev/project-site.html
On 19/02/2020 18:40, Roy Lenferink wrote:
> (inline comments)
>
> On 2020/02/19 17:04:56, Andy Seaborne <an...@apache.org> wrote:
>>
>> Sorry, I haven't had time to investigate all the machinery but if the
>> javadoc is a different branch or repo, how does publish happen? And not
>> happen for changes during the development cycle?
>>
>
> Publishing right now happens by checking out the 'production' site and adding the javadocs to there.
> Publishing in the git way would happen by adding the generated javadocs to a separate branch or
> repository.
>
> Right now jena.a.o is served using SVN (config here [1]). In these config files it is possible to specify
> multiple lines and specify a subfolder as well. E.g. what beam is doing here [2].
>
> The following could make sense for jena:
> /www/jena.apache.org: $gitbox/jena-site
> /www/jena.apache.org/content/documentation/javadoc: $gitbox/jena-site:release-docs
>
> This means:
> - That the 'master' branch will contain the sources for the site
> - That the 'asf-site' branch will contain the generated output for the site
> - That the 'release-docs' branch will contain additional files which will be served at http://jena.apache.org/documentation/javadoc/
>
>>
>> I know infra is working on a CMS replacement and/or guidelines. Is this
>> it? Is it compatible? I thought they were going to have a buildbot2.
>>
>
> Infra currently offers pelican and jekyll as 'replacements' for the CMS. However, Infra is also testing
> a new build approach were the project can more or less define how their site is build [3]. This could
> be a script to e.g. retrieve and execute Hugo.
>
> I already had a quick chat with Infra about how to implement support for Hugo (e.g. next to Jekyll
> and Pelican) but we decided that the new build approach will probably be a better fit.
>
>>>
>>> Good to hear the community is interested in this :)
>>
>> TBC: I am interested - I can't speak for the community.
>
> My bad. I made the quick assumption by taking 2 responses and calling that 'the community', which is
> almost never the case, oops!
>
>>
>
> Let me know if any additional information is needed.
>
> Roy
>
> [1] https://github.com/apache/infrastructure-puppet/blob/5bd3b7cc8bd6d8f2698a6e0cac1f421dd960ddf0/modules/svnwcsub/files/svnwcsub.conf#L115
> [2] https://github.com/apache/infrastructure-puppet/blob/5bd3b7cc8bd6d8f2698a6e0cac1f421dd960ddf0/modules/gitwcsub/files/config/gitwcsub.cfg#L49-L50
> [3] https://lists.apache.org/thread.html/rf0d4fef9b65e1ef346bc71b66253f9e54f15e048be6d011751a24ae0%40%3Cdev.community.apache.org%3E
>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Roy Lenferink <rl...@apache.org>.
(inline comments)
On 2020/02/19 17:04:56, Andy Seaborne <an...@apache.org> wrote:
>
> Sorry, I haven't had time to investigate all the machinery but if the
> javadoc is a different branch or repo, how does publish happen? And not
> happen for changes during the development cycle?
>
Publishing right now happens by checking out the 'production' site and adding the javadocs to there.
Publishing in the git way would happen by adding the generated javadocs to a separate branch or
repository.
Right now jena.a.o is served using SVN (config here [1]). In these config files it is possible to specify
multiple lines and specify a subfolder as well. E.g. what beam is doing here [2].
The following could make sense for jena:
/www/jena.apache.org: $gitbox/jena-site
/www/jena.apache.org/content/documentation/javadoc: $gitbox/jena-site:release-docs
This means:
- That the 'master' branch will contain the sources for the site
- That the 'asf-site' branch will contain the generated output for the site
- That the 'release-docs' branch will contain additional files which will be served at http://jena.apache.org/documentation/javadoc/
>
> I know infra is working on a CMS replacement and/or guidelines. Is this
> it? Is it compatible? I thought they were going to have a buildbot2.
>
Infra currently offers pelican and jekyll as 'replacements' for the CMS. However, Infra is also testing
a new build approach were the project can more or less define how their site is build [3]. This could
be a script to e.g. retrieve and execute Hugo.
I already had a quick chat with Infra about how to implement support for Hugo (e.g. next to Jekyll
and Pelican) but we decided that the new build approach will probably be a better fit.
> >
> > Good to hear the community is interested in this :)
>
> TBC: I am interested - I can't speak for the community.
My bad. I made the quick assumption by taking 2 responses and calling that 'the community', which is
almost never the case, oops!
>
Let me know if any additional information is needed.
Roy
[1] https://github.com/apache/infrastructure-puppet/blob/5bd3b7cc8bd6d8f2698a6e0cac1f421dd960ddf0/modules/svnwcsub/files/svnwcsub.conf#L115
[2] https://github.com/apache/infrastructure-puppet/blob/5bd3b7cc8bd6d8f2698a6e0cac1f421dd960ddf0/modules/gitwcsub/files/config/gitwcsub.cfg#L49-L50
[3] https://lists.apache.org/thread.html/rf0d4fef9b65e1ef346bc71b66253f9e54f15e048be6d011751a24ae0%40%3Cdev.community.apache.org%3E
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Andy Seaborne <an...@apache.org>.
On 16/02/2020 18:38, Roy Lenferink wrote:
> Hi Andy,
>
> Thanks for your answer!
>
> I can confirm it is easier to use Hugo on Windows compared to Jekyll (I am generating and testing
> using the Ubuntu shell on Windows). Just downloading the tarball containing the Hugo binary and
> you're good to go. With Jekyll the process is a bit more complex as it requires some specific Ruby
> stuff.
>
> (see my inline comments below as well)
>
> On 2020/02/16 17:06:59, Andy Seaborne <an...@apache.org> wrote:
>> Hi Roy - looks good! Thanks for pushing this along.#
>>
>> We had discussed this using Jekyll (because GH uses Jekyll) but I read
>> that installation on Windows is easier for Hugo (the speed issue does not
>> look like such an advantage for us) - and that that is helpful to get more
>> contributions. CMS and "improve this page" editing has had a reasonable
>> amount of use over the years but we do need to migrate away from CMS.
>
> And this is something that will be kept in place, however instead of a redirect to the Apache CMS
> it will open the GitHub editor with the file for the page the person is viewing at that moment.
>
>>
>> Was conversion quite smooth? Any discoveries?
>> What's the markdown like? I don't know of anything special except of course
>> tables.
>>
>
> Most of it was just putting the pieces together. The CMS skeleton.html could --with a few minor
> changes-- be re-used as Hugo template. The pages of the website were already written in
> markdown and only the header of the file needed to be changed (old: [1], new [2]), the content of the
> pages could just be re-used. Basically whatever syntax markdown supports is supported by Hugo [3].
>
>> Managing javadoc separately would be nice. Putting a lot of javadoc into
>> svn is a bit clunky.
>>
>
> Well, in the end the data still needs to be stored somewhere. However, in this case I'd suggest to put
> it in a separate branch because in that way it is still possible for others to clone the site without the
> huge javadoc collection.
Sorry, I haven't had time to investigate all the machinery but if the
javadoc is a different branch or repo, how does publish happen? And not
happen for changes during the development cycle?
I know infra is working on a CMS replacement and/or guidelines. Is this
it? Is it compatible? I thought they were going to have a buildbot2.
>
> An alternative could be a complete separate repository, e.g. jena-release-docs, which contains all the
> javadoc documentation, but this is just a matter of preference.
>
>>
>> Andy
>>
>
> Good to hear the community is interested in this :)
TBC: I am interested - I can't speak for the community.
>
> Best,
> Roy
>
> [1] https://svn.apache.org/repos/asf/jena/site/trunk/content/getting_involved/reviewing_contributions.mdtext
> [2] https://raw.githubusercontent.com/rlenferink/jena-site/110a42f109b25b9771f55a500cfffcb0593544f0/source/getting_involved/reviewing_contributions.md
> [3] https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Roy Lenferink <rl...@apache.org>.
Hi Andy,
Thanks for your answer!
I can confirm it is easier to use Hugo on Windows compared to Jekyll (I am generating and testing
using the Ubuntu shell on Windows). Just downloading the tarball containing the Hugo binary and
you're good to go. With Jekyll the process is a bit more complex as it requires some specific Ruby
stuff.
(see my inline comments below as well)
On 2020/02/16 17:06:59, Andy Seaborne <an...@apache.org> wrote:
> Hi Roy - looks good! Thanks for pushing this along.#
>
> We had discussed this using Jekyll (because GH uses Jekyll) but I read
> that installation on Windows is easier for Hugo (the speed issue does not
> look like such an advantage for us) - and that that is helpful to get more
> contributions. CMS and "improve this page" editing has had a reasonable
> amount of use over the years but we do need to migrate away from CMS.
And this is something that will be kept in place, however instead of a redirect to the Apache CMS
it will open the GitHub editor with the file for the page the person is viewing at that moment.
>
> Was conversion quite smooth? Any discoveries?
> What's the markdown like? I don't know of anything special except of course
> tables.
>
Most of it was just putting the pieces together. The CMS skeleton.html could --with a few minor
changes-- be re-used as Hugo template. The pages of the website were already written in
markdown and only the header of the file needed to be changed (old: [1], new [2]), the content of the
pages could just be re-used. Basically whatever syntax markdown supports is supported by Hugo [3].
> Managing javadoc separately would be nice. Putting a lot of javadoc into
> svn is a bit clunky.
>
Well, in the end the data still needs to be stored somewhere. However, in this case I'd suggest to put
it in a separate branch because in that way it is still possible for others to clone the site without the
huge javadoc collection.
An alternative could be a complete separate repository, e.g. jena-release-docs, which contains all the
javadoc documentation, but this is just a matter of preference.
>
> Andy
>
Good to hear the community is interested in this :)
Best,
Roy
[1] https://svn.apache.org/repos/asf/jena/site/trunk/content/getting_involved/reviewing_contributions.mdtext
[2] https://raw.githubusercontent.com/rlenferink/jena-site/110a42f109b25b9771f55a500cfffcb0593544f0/source/getting_involved/reviewing_contributions.md
[3] https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Andy Seaborne <an...@apache.org>.
Hi Roy - looks good! Thanks for pushing this along.#
We had discussed this using Jekyll (because GH uses Jekyll) but I read
that installation on Windows is easier for Hugo (the speed issue does not
look like such an advantage for us) - and that that is helpful to get more
contributions. CMS and "improve this page" editing has had a reasonable
amount of use over the years but we do need to migrate away from CMS.
Was conversion quite smooth? Any discoveries?
What's the markdown like? I don't know of anything special except of course
tables.
Managing javadoc separately would be nice. Putting a lot of javadoc into
svn is a bit clunky.
Andy
On Sun, 16 Feb 2020 at 12:37, Roy Lenferink <rl...@apache.org> wrote:
> Hi Claude,
>
> Thanks for your email and thoughts! I wasn't aware of Disqus and its
> privacy policy. After checking I
> think you are talking about the following page [1]? On that page the
> following 2 statements are
> present:
> - "To use Hugo’s Disqus template, you first need to set a single value in
> your site’s config.toml or
> config.yml"
> - "To add Disqus, include the following line in templates where you want
> your comments to appear"
>
> However, using Disqus is not something we are doing [2]. This can be
> verified by e.g. doing the
> following:
>
> Roy@BTO-ROY:~/workspace/asf/jena-site$ hugo
>
> | EN
> -------------------------+------
> Pages | 230
> Paginator pages | 0
> Non-page files | 0
> Static files | 136
> Processed images | 0
> Aliases | 0
> Sitemaps | 1
> Cleaned | 0
>
> Total in 465 ms
>
> Roy@BTO-ROY:~/workspace/asf/jena-site$ grep -ri disqus
>
> Hugo writes the following [3] and how to disable specific options in the
> config.toml file [4].
>
> I think this clarifies your doubts, can you confirm?
>
> An alternative would be using e.g. Jekyll which I did some tests with as
> well. Jekyll can be extended
> with a lot of different plugins, however Hugo is easier to setup (single
> static binary) and faster to
> generate the site compared to Jekyll [5] (no metrics from me personally).
>
> Roy
>
> [1] https://gohugo.io/templates/internal/#configure-disqus
> [2] https://github.com/rlenferink/jena-site/blob/master/config.toml
> [3] https://gohugo.io/about/hugo-and-gdpr/
> [4] https://gohugo.io/about/hugo-and-gdpr/#disable-all-services
> [5] https://forestry.io/blog/hugo-vs-jekyll-benchmark/
>
> On 2020/02/16 11:34:28, Claude Warren <cl...@xenei.com> wrote:
> > I think this can be the first step in making the entire site deployment
> > process more automated and keeps us moving forward with supported
> > technologies.
> >
> > However, I note that the Hugo documentation states: "Hugo ships with an
> > internal Disqus template". I am concerned that the Discus connection may
> > not meet with the Apache Foundation's approach to privacy and data
> > sharing. I know there are problems with surveys and polls hosted by 3rd
> > parties.
> >
> > So:
> > +1 for moving to site to git.
> > -1 for using Hugo unless it can be deployed without 3rd party data
> sharing
> > or unless there is approval from Apache legal.
> >
> > Claude
> >
> > On Sat, Feb 15, 2020 at 1:28 PM Roy Lenferink <rl...@apache.org>
> wrote:
> >
> > > Hi Jena community,
> > >
> > > I noticed Jena is still serving its site from SVN with help of the
> Apache
> > > CMS. At the Apache Celix
> > > project we decided to move away from the CMS and move towards git for
> > > serving our website [1].
> > > This because the CMS was introduced in 2010 and is currently not
> accepting
> > > any new projects. With
> > > the move to Hugo we're sure that we still can update the site when the
> ASF
> > > CMS will be
> > > decommissioned.
> > >
> > > The master branch contains the actual website sources whereas the
> > > generated website is served
> > > from the asf-site branch. Hugo is being used as static website
> generator.
> > > Content is written in
> > > Markdown.
> > >
> > > I had a look at Jena its site and it was quite easy to migrate Jena its
> > > site to use Hugo as well. An
> > > example of Hugo its output is (for demo purposes only) available on
> [2].
> > > These are the existing
> > > markdown files with a slightly changed header.
> > >
> > > Moving to git can enlarge the visibility of how projects are
> functioning.
> > > Next to that, new contributors
> > > can simply create a pull request against the website repository if they
> > > find anything they want to
> > > improve. I've updated the 'Improve this page' to 'Edit this page' which
> > > will open the GitHub webpage
> > > to edit the currently viewed page (currently returning a 404 because
> the
> > > apache/jena-site repository
> > > does not exist).
> > >
> > > If the community is interested in this move what I propose:
> > > - Someone from the PMC to request a new git repository for the website
> > > (e.g. jena-site) via [4]
> > > - Me creating the pull request from the repository I am temporarily
> using
> > > for the website contents [5]
> > > to the official jena-site repository
> > > - Create a Jenkins job to automatically build the site after changes
> > > happen on the master branch.
> > > - When the pull request is reviewed and merged ask INFRA to move over
> from
> > > the current svnpubsub
> > > to the gitpubsub approach and remove Jena from the Apache CMS.
> > >
> > > Next to that Jena is also providing javadocs on its site. My proposal
> for
> > > this is to serve them from a
> > > separate branch (e.g. release-docs). This way people who only want to
> > > clone the site can clone the
> > > the master branch using --single-branch and will not be bothered with
> > > cloning all the javadocs.
> > >
> > > All the URLs are still the same so the SEO score is not influenced in
> any
> > > way.
> > >
> > > I'd like to hear everyone's opinion on this :)
> > >
> > > Best regards,
> > > Roy
> > >
> > > [1] https://github.com/apache/celix-site
> > > [2] http://jena.roylenferink.nl/
> > > [3] http://celix.apache.org/contributing/releasing.html
> > > [4] https://gitbox.apache.org/setup/newrepo.html
> > > [5] https://github.com/rlenferink/jena-site
> > >
> >
> >
> > --
> > I like: Like Like - The likeliest place on the web
> > <http://like-like.xenei.com>
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Roy Lenferink <rl...@apache.org>.
Hi Claude,
Thanks for your email and thoughts! I wasn't aware of Disqus and its privacy policy. After checking I
think you are talking about the following page [1]? On that page the following 2 statements are
present:
- "To use Hugo’s Disqus template, you first need to set a single value in your site’s config.toml or
config.yml"
- "To add Disqus, include the following line in templates where you want your comments to appear"
However, using Disqus is not something we are doing [2]. This can be verified by e.g. doing the
following:
Roy@BTO-ROY:~/workspace/asf/jena-site$ hugo
| EN
-------------------------+------
Pages | 230
Paginator pages | 0
Non-page files | 0
Static files | 136
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 465 ms
Roy@BTO-ROY:~/workspace/asf/jena-site$ grep -ri disqus
Hugo writes the following [3] and how to disable specific options in the config.toml file [4].
I think this clarifies your doubts, can you confirm?
An alternative would be using e.g. Jekyll which I did some tests with as well. Jekyll can be extended
with a lot of different plugins, however Hugo is easier to setup (single static binary) and faster to
generate the site compared to Jekyll [5] (no metrics from me personally).
Roy
[1] https://gohugo.io/templates/internal/#configure-disqus
[2] https://github.com/rlenferink/jena-site/blob/master/config.toml
[3] https://gohugo.io/about/hugo-and-gdpr/
[4] https://gohugo.io/about/hugo-and-gdpr/#disable-all-services
[5] https://forestry.io/blog/hugo-vs-jekyll-benchmark/
On 2020/02/16 11:34:28, Claude Warren <cl...@xenei.com> wrote:
> I think this can be the first step in making the entire site deployment
> process more automated and keeps us moving forward with supported
> technologies.
>
> However, I note that the Hugo documentation states: "Hugo ships with an
> internal Disqus template". I am concerned that the Discus connection may
> not meet with the Apache Foundation's approach to privacy and data
> sharing. I know there are problems with surveys and polls hosted by 3rd
> parties.
>
> So:
> +1 for moving to site to git.
> -1 for using Hugo unless it can be deployed without 3rd party data sharing
> or unless there is approval from Apache legal.
>
> Claude
>
> On Sat, Feb 15, 2020 at 1:28 PM Roy Lenferink <rl...@apache.org> wrote:
>
> > Hi Jena community,
> >
> > I noticed Jena is still serving its site from SVN with help of the Apache
> > CMS. At the Apache Celix
> > project we decided to move away from the CMS and move towards git for
> > serving our website [1].
> > This because the CMS was introduced in 2010 and is currently not accepting
> > any new projects. With
> > the move to Hugo we're sure that we still can update the site when the ASF
> > CMS will be
> > decommissioned.
> >
> > The master branch contains the actual website sources whereas the
> > generated website is served
> > from the asf-site branch. Hugo is being used as static website generator.
> > Content is written in
> > Markdown.
> >
> > I had a look at Jena its site and it was quite easy to migrate Jena its
> > site to use Hugo as well. An
> > example of Hugo its output is (for demo purposes only) available on [2].
> > These are the existing
> > markdown files with a slightly changed header.
> >
> > Moving to git can enlarge the visibility of how projects are functioning.
> > Next to that, new contributors
> > can simply create a pull request against the website repository if they
> > find anything they want to
> > improve. I've updated the 'Improve this page' to 'Edit this page' which
> > will open the GitHub webpage
> > to edit the currently viewed page (currently returning a 404 because the
> > apache/jena-site repository
> > does not exist).
> >
> > If the community is interested in this move what I propose:
> > - Someone from the PMC to request a new git repository for the website
> > (e.g. jena-site) via [4]
> > - Me creating the pull request from the repository I am temporarily using
> > for the website contents [5]
> > to the official jena-site repository
> > - Create a Jenkins job to automatically build the site after changes
> > happen on the master branch.
> > - When the pull request is reviewed and merged ask INFRA to move over from
> > the current svnpubsub
> > to the gitpubsub approach and remove Jena from the Apache CMS.
> >
> > Next to that Jena is also providing javadocs on its site. My proposal for
> > this is to serve them from a
> > separate branch (e.g. release-docs). This way people who only want to
> > clone the site can clone the
> > the master branch using --single-branch and will not be bothered with
> > cloning all the javadocs.
> >
> > All the URLs are still the same so the SEO score is not influenced in any
> > way.
> >
> > I'd like to hear everyone's opinion on this :)
> >
> > Best regards,
> > Roy
> >
> > [1] https://github.com/apache/celix-site
> > [2] http://jena.roylenferink.nl/
> > [3] http://celix.apache.org/contributing/releasing.html
> > [4] https://gitbox.apache.org/setup/newrepo.html
> > [5] https://github.com/rlenferink/jena-site
> >
>
>
> --
> I like: Like Like - The likeliest place on the web
> <http://like-like.xenei.com>
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Claude Warren <cl...@xenei.com>.
I think this can be the first step in making the entire site deployment
process more automated and keeps us moving forward with supported
technologies.
However, I note that the Hugo documentation states: "Hugo ships with an
internal Disqus template". I am concerned that the Discus connection may
not meet with the Apache Foundation's approach to privacy and data
sharing. I know there are problems with surveys and polls hosted by 3rd
parties.
So:
+1 for moving to site to git.
-1 for using Hugo unless it can be deployed without 3rd party data sharing
or unless there is approval from Apache legal.
Claude
On Sat, Feb 15, 2020 at 1:28 PM Roy Lenferink <rl...@apache.org> wrote:
> Hi Jena community,
>
> I noticed Jena is still serving its site from SVN with help of the Apache
> CMS. At the Apache Celix
> project we decided to move away from the CMS and move towards git for
> serving our website [1].
> This because the CMS was introduced in 2010 and is currently not accepting
> any new projects. With
> the move to Hugo we're sure that we still can update the site when the ASF
> CMS will be
> decommissioned.
>
> The master branch contains the actual website sources whereas the
> generated website is served
> from the asf-site branch. Hugo is being used as static website generator.
> Content is written in
> Markdown.
>
> I had a look at Jena its site and it was quite easy to migrate Jena its
> site to use Hugo as well. An
> example of Hugo its output is (for demo purposes only) available on [2].
> These are the existing
> markdown files with a slightly changed header.
>
> Moving to git can enlarge the visibility of how projects are functioning.
> Next to that, new contributors
> can simply create a pull request against the website repository if they
> find anything they want to
> improve. I've updated the 'Improve this page' to 'Edit this page' which
> will open the GitHub webpage
> to edit the currently viewed page (currently returning a 404 because the
> apache/jena-site repository
> does not exist).
>
> If the community is interested in this move what I propose:
> - Someone from the PMC to request a new git repository for the website
> (e.g. jena-site) via [4]
> - Me creating the pull request from the repository I am temporarily using
> for the website contents [5]
> to the official jena-site repository
> - Create a Jenkins job to automatically build the site after changes
> happen on the master branch.
> - When the pull request is reviewed and merged ask INFRA to move over from
> the current svnpubsub
> to the gitpubsub approach and remove Jena from the Apache CMS.
>
> Next to that Jena is also providing javadocs on its site. My proposal for
> this is to serve them from a
> separate branch (e.g. release-docs). This way people who only want to
> clone the site can clone the
> the master branch using --single-branch and will not be bothered with
> cloning all the javadocs.
>
> All the URLs are still the same so the SEO score is not influenced in any
> way.
>
> I'd like to hear everyone's opinion on this :)
>
> Best regards,
> Roy
>
> [1] https://github.com/apache/celix-site
> [2] http://jena.roylenferink.nl/
> [3] http://celix.apache.org/contributing/releasing.html
> [4] https://gitbox.apache.org/setup/newrepo.html
> [5] https://github.com/rlenferink/jena-site
>
--
I like: Like Like - The likeliest place on the web
<http://like-like.xenei.com>
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [DISCUSS] Moving Jena site from Apache CMS/SVN to Git
Posted by Roy Lenferink <rl...@apache.org>.
Hi all,
I think most (definitely valid) points have been addressed. I'll start a vote for this shortly.
Roy
On 2020/02/15 13:28:11, Roy Lenferink <rl...@apache.org> wrote:
> Hi Jena community,
>
> I noticed Jena is still serving its site from SVN with help of the Apache CMS. At the Apache Celix
> project we decided to move away from the CMS and move towards git for serving our website [1].
> This because the CMS was introduced in 2010 and is currently not accepting any new projects. With
> the move to Hugo we're sure that we still can update the site when the ASF CMS will be
> decommissioned.
>
> The master branch contains the actual website sources whereas the generated website is served
> from the asf-site branch. Hugo is being used as static website generator. Content is written in
> Markdown.
>
> I had a look at Jena its site and it was quite easy to migrate Jena its site to use Hugo as well. An
> example of Hugo its output is (for demo purposes only) available on [2]. These are the existing
> markdown files with a slightly changed header.
>
> Moving to git can enlarge the visibility of how projects are functioning. Next to that, new contributors
> can simply create a pull request against the website repository if they find anything they want to
> improve. I've updated the 'Improve this page' to 'Edit this page' which will open the GitHub webpage
> to edit the currently viewed page (currently returning a 404 because the apache/jena-site repository
> does not exist).
>
> If the community is interested in this move what I propose:
> - Someone from the PMC to request a new git repository for the website (e.g. jena-site) via [4]
> - Me creating the pull request from the repository I am temporarily using for the website contents [5]
> to the official jena-site repository
> - Create a Jenkins job to automatically build the site after changes happen on the master branch.
> - When the pull request is reviewed and merged ask INFRA to move over from the current svnpubsub
> to the gitpubsub approach and remove Jena from the Apache CMS.
>
> Next to that Jena is also providing javadocs on its site. My proposal for this is to serve them from a
> separate branch (e.g. release-docs). This way people who only want to clone the site can clone the
> the master branch using --single-branch and will not be bothered with cloning all the javadocs.
>
> All the URLs are still the same so the SEO score is not influenced in any way.
>
> I'd like to hear everyone's opinion on this :)
>
> Best regards,
> Roy
>
> [1] https://github.com/apache/celix-site
> [2] http://jena.roylenferink.nl/
> [3] http://celix.apache.org/contributing/releasing.html
> [4] https://gitbox.apache.org/setup/newrepo.html
> [5] https://github.com/rlenferink/jena-site
>