Create bare site shell - Githubissues

ronaldtse commented 6 years ago

@strogonoff could you help create an Open Project site in this repo for Riffol? Thanks!

drystone commented 6 years ago

We're hoping to be able to distribute binaries for Riffol. Can we include a download page and a mechanism to upload binaries with checksums and maybe trigger a rebuild of the page? Thanks!

strogonoff commented 6 years ago

@drystone

Can we include a download page and a mechanism to upload binaries with checksums and maybe trigger a rebuild of the page?

I think so. Open Project site suite doesn’t offer a ready-made mechanism for that yet, but we can make this work and start with Riffol as the pilot.

First off, do you think you could use GitHub’s releases feature[0] to offer binaries for download? I believe we’ll be able to hotlink those from documentation pages, and you can provide checksums as part of release notes[1].

It’s possible to automate the release by triggering binary build on each qualifying commit or tag, for example, and publishing a release using GitHub API if tests & build succeed. The whole process could stay between the build box and GitHub.

The same build-release automation could indeed hook into Open Project site CI (I believe it’s currently Jenkins) and simply trigger a Jekyll build whenever a release is published. Apart for that call, Open Project site infrastructure would be left out of this, reducing coupling and attack surface.

You could also go full-on Semantic Release[2] and forget about managing tags & releases at all, although I’m not sure if SR in its current state works with Rust-based packages.

I would prefer to avoid extending Open Project site suite to include binary-hosting infrastructure. It’s a liability and maintenance headache (ramifications of a hack would mean distributing contaminated binaries—checksums can be compromised and let’s be honest, few people actually verify checksums anyway). We’d be reinventing a few wheels as well, implementing release APIs and security measures that GitHub and probably Gitlab already offer. I’m up for discussing this though, we could open a feature request against the Open Project theme.

References:

[0] GitHub Releases
[1] GitHub release example with binary downloads & checksums
[2] Semantic release (using it with a Node package I’ve created. With it properly set up you only worry about accurate commit messages, and CI takes care of building and releasing patch/minor/major versions based on what changed between commits. It also publishes released versions to GitHub and package registry)

strogonoff commented 6 years ago

As of bare site shell, depending on how to judge it’s from 60% to 80% complete.

To enable deployment, should I just adapt Jenkinsfile/Rakefile from metanorma.com repo? (@ronaldtse)

ronaldtse commented 6 years ago

I agree, let’s just use the Github releases page for downloading binaries for now.

@strogonoff yes, just adapt the Jenkinsfile and it’ll work!

drystone commented 6 years ago

@strogonoff, yes I fully agree with the above - on re-reading I suspect that is what @ronaldtse had in mind when he mentioned the 'Releases section in this repo'. Not storing binaries along with the code as I'd mistakenly assumed!

There is no official Riffol release as yet but a rolling 'latest' based on master will be perfect for now.

What do you need in terms of documentation (content/markup/structure)?

strogonoff commented 6 years ago

@drystone at this point it’s fine, I’ve forked the repo to work inside a new docs/ subdirectory for a bit, port some of the README and prepare the foundation for the rest. The Open Project concept currently leaves specific documentation structure down to each individual project.

strogonoff commented 6 years ago

As to markup, I’m working on AsciiDoc support in Open Project theme but worst case we’ll have Markdown first and later switch to AsciiDoc

strogonoff commented 6 years ago

Implemented the basic site a while ago. For now the docs are based on README, pending reorganization

drystone commented 6 years ago

Thanks @stroganoff, this is a good start. Nice '> Riffol' logo :) I guess 'Software' might link to the GitHub repo main page and GitHub releases like the download button. When I get a chance, I'll upload to crates.io so a link there would be needed too. And feel free to put me (john@drystone.co.uk) in Contacts along with a link to the repo issues page. I expect Ronald will have a Ribose address to put up too.

strogonoff commented 6 years ago

@drystone For the ‘Software’ link, it is redundant the way it works now, should be fixed as part of https://github.com/riboseinc/jekyll-theme-open-project/issues/33. Regarding the GitHub issues link, I reckon the GitHub repo link covers that? Either way I suggest to hang on for a bit until that issue is closed, site layout will be a bit different then and those issues may no longer be a thing.

‘Contacts’ links to Ribose Open email on all sites, this may become customizable soon.

Happy you liked the logo too, it was created for Riffol by Eva Lee (https://eval.ee/). It’s a rust-colored salmon (IMO quite cute) which ties it to riffle & Rust

PS for your info, your mention pinged another guy, my last name is not spelled as people usually expect ;)

drystone commented 6 years ago

Whoops, sorry @strogonoff - I'm not sure there even is a @stroganoff!

riboseinc / riffol.github.io

Create bare site shell #1