Hi folks, Following up on this.
After doing a bit of research I noticed Apache Beam is doing something similar that could be useful for Apache MINA as well.Their generated documentation is hosted on a separate branch, e.g. release-docs [1] which is then propagated into the site [2]. This can either be a separate branch (e.g. release-docs) and then described in the README when cloning the repository to only clone using '--single-branch --branch master' when making minor changes. It could also be a complete separate repository (e.g. mina-release-docs), but personally I'd go for the separate branch. Release managers have to checkout the whole repository anyway (and otherwise always work with 2 separate repositories) and for new contributors it will be clear where the release documentation for the site is origination from. I'd like to hear your opinions on this. If no -1, a MINA PMC member can request the mina-site repository [3] and I'll create a pull request against it. Best, Roy [1] https://github.com/apache/beam-site/tree/release-docs [2] https://beam.apache.org/releases/javadoc/2.16.0/ [3] https://gitbox.apache.org/setup/newrepo.html On 2020/02/11 13:22:32, Roy Lenferink <rlenfer...@apache.org> wrote: > Hi Emmanuel, > > Thanks for your reply! See my inline comments. > > On 2020/02/10 23:34:29, Emmanuel Lécharny <elecha...@gmail.com> wrote: > > Hi Roy, > > > > On 10/02/2020 16:00, Roy Lenferink wrote: > > > Hello MINA developers, > > > > > > I noticed MINA is still serving its site from SVN with help of the Apache > > > CMS. > > > > Yes. It has been this way for around a decade (actually, as soon as the > > CMS was proposed). before that we were using a buggy Confluence -> > > website generator. > > > > > > > At the Apache Celix project we decided to move away from the CMS and move > > > towards git for serving our website [1]. 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. > > > > > > How different is it from the CMS syntax ? We have quite a complex > > template to manage the sub-projects, and I would be interested to know > > what it meant to convert the MINA site from The ASF CMS to Hugo... > > > > If you mean the content written on the site, that will still be in Markdown. > If you mean the templates > for the different subprojects (SSHD, FtpServer etc..), Hugo provides so > called 'layouts' for them. > If already experimented with this here: > https://github.com/rlenferink/mina-site/tree/master/layouts > And this results in the same look and feel the current website has. Duplicate > code is minimized > because Hugo provides the ability to include files as well from within its > template. > > Different styles: > - http://mina.roylenferink.nl/ > - http://mina.roylenferink.nl/mina-project/mina-project.html > - http://mina.roylenferink.nl/asyncweb-project/asyncweb-project.html > - http://mina.roylenferink.nl/ftpserver-project/ftpserver-project.html > - http://mina.roylenferink.nl/sshd-project/sshd-project.html > - http://mina.roylenferink.nl/vysper-project/vysper-project.html > > And the user guide still functions as well: > http://mina.roylenferink.nl/mina-project/userguide/ch1-getting-started/ch1.2-why-mina.html > > (above pages are all generated using Hugo) > > > > > > > > > I experimented a bit with MINA its site and have something working with > > > Hugo > > > as well now. An example of its output is (for demo purposes only) > > > available > > > on [2] > > > > > > Moving to git can enlarge the visibility of how projects are functioning. > > > Next > > > to that, new contributors can just create a pull request against the > > > website > > > repository if they find anything they want to improve. And a 'Edit on > > > GitHub' > > > button can be added as well to the site, e.g. an example of a page on the > > > Celix website [3] > > > > I'm quite interesting to move away from the ASF CMS for at least 3 reasons : > > > > - git > > > > - being sure that we still can update the site when the ASF CMS will be > > decommissioned. > > > > Which is why I started this thread. The CMS has been introduced 10 years ago > and new > projects are not allowed to use the CMS anymore. Probably projects will > indeed have to move to an > alternative solution when the ASF CMS will be decommissioned. > > > - generated docs update are a PITA (with frequent removal of them due to > > some bad manipulations) > > > > > > OTOH, I don't want to spend days on such a task... > > > > The website in general is already converted to use Hugo as static content > generator. > The main changes where making sure the the page headers were changed from: > Title: <page name> > Notice: <ASF Notice> > > to the Hugo syntax > type: <page layout> > title: <page name> > > Next to that some code-snippets had to be updated from e.g. :::java to > ```java (the Markdown > approach). But that is done as well already. > > About the not wanting to spent days: I am offering my help as well with this > migration process so > projects will become independent about the way their sites are being served. > > > > > > > > > If the community is interested in this move what I propose: > > > - Someone from the PMC to request a new git repository for the website via > > > [4] called e.g. mina-site > > > - Me creating the pull request from the repository I am temporarily using > > > for the website contents [5] to the official mina-site repository > > > - In the meantime discuss with INFRA about the best way to host the > > > gen-docs (it could be part of the repo in the /static/ folder, however if > > > there > > > is a better way it is best to discuss this upfront). > > > > yes, this is a kind of a concern. Any system that is simpler than what > > we currently have withe The ASF CMSl would be a relief. I can't count > > the number of times I have had to reinject those generated doc because > > there was a mistake and they were simply removed by the process... > > > > As a new person having a look at MINA its website I first had a look at the > mina/site folder in SVN but > completely missed the gen-docs. Had to spent some time to figure out were it > was being served from > and what the extpaths.txt exactly was meant for (in the end found the > solution in the MINA Developers > Guide). > > > > > > - 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 MINA > > > from the Apache CMS. > > > > > > I'd like to hear everyone's opinion on this :) > > > > All in all, I'm interested ! > > > > Good to hear :) I'll ask around a bit about possibilities for serving the > /gen-docs/ folder (knowing > serving from git can be an option but maybe there are better alternatives for > this). > > > > > Thanks ! > > > > > > > > > > Best regards, > > > Roy > > > > > > [1] https://github.com/apache/celix-site > > > [2] http://mina.roylenferink.nl/ > > > [3] http://celix.apache.org/contributing/releasing.html > > > [4] https://gitbox.apache.org/setup/newrepo.html > > > [5] https://github.com/rlenferink/mina-site > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@mina.apache.org > For additional commands, e-mail: dev-h...@mina.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@mina.apache.org For additional commands, e-mail: dev-h...@mina.apache.org
