Move from Heroku to Github Pages

[onebree]

Previous participants: @andreareginato , @akz92

As discussed in issue #146, we want to move away from Heroku and instead host the site on Github. Some advantages include:

• Quicker deployment
• Free site hosting (by Github)
• Built-in Markdown support when using Jekyll
• Little to no required downtime
• No need to give collaborators access to an additional service (Heroku)
• Others can easily test their pull requests by calling: jekyll serve -h 0.0.0.0 -p 4000

To see a current live demo of the beta site: https://github.com/akz92/akz92.github.io

Checklist of features for demo site:

• [x] Syntax highlighting (Ruby)
• [x] Mobile-friendly website (Current responsive behavior is not mobile friendly akz92/akz92.github.io#1)
• [ ] Disqus compatibility (hopefully deprecating Github issues as "thoughts".
  • Open to other discussion platforms that possibly recognize Markdown.
• [ ] Tedious, but change all tabs to spaces in code (huge pet-peeve of mine!)

Please place all discussion about the site construction here!

[benoittgt]

First thanks a lot for the job done.

Do you have a task list of missing stuff for this new version?

[onebree]

@benoittgt not at the moment. I have not inspected the demo very much. I will add a checklist to the parent comment before next week.

[onebree]

@benoittgt I finally added the checklist to the master comment!

@andreareginato I found out that Gitbook now allows for discussion boards and in-line comments for a publication.

• https://www.gitbook.com/blog/features/discussions
• Unlimited public projects for free (should not be an issue)
• Provides documentation-like navigation
• Allows for custom landing page
• Example free gitbook: https://github.com/DjangoGirls/tutorial

I know I was extremely excited about the Jekyll site. I just wanted to know your thoughts on this new thing I found.

[franzejr]

I think Gitbook is pretty awesome and simple.

[onebree]

@franzejr yes, gitbook is good. IIRC, there were other OSS alternatives out there, but I cannot find which ones. If you do, let me know so I can review them as well. I think anything like Gitbook would allow for quicker releases, and less worrying about the design. (Which is the current hold-up)

@akz92 - I want to say thank you for all you have done porting the site so far to Jekyll. Unfortunately, I have not had time to really rummage through it or launch locally. I would like you know you and @andreareginato thoughts on Gitbook. Like I just said, it would mean less time worrying about design details and more time thinking about content.

[dankohn]

Positives of Gitbook are that it looks nice and would enable free downloads of the contents as eBooks and PDFs, which some users would I'm sure like.

Downside is that Gitbook/GitHub integration is only one way. When any change is made to the Github repo, it will automatically propagate to the Gitbook. And, using the GitBook editor will make changes to the Github repo. But, these changes will not be automatically compiled into HTML usable by Github Pages to actually display the website. To update the website would require an additional step of an authorized committer re-rendering the webpages and uploading to Github. By contrast, a Jekyll back-end will automatically update Github Pages on every commit.

It does seem possible to setup a Travis post-commit hook that would automatically render the Github Pages HTML and commit them back to the repo, as documented. But that would be some meaningful additional work.

[onebree]

@dankohn git hooks are on my list of things to learn. My comment from 11/09 suggests we would use Gitbook instead of Jekyll. However, if Gitbook limits the design customization (no response from them yet), then a Github Pages site would still be handy.

If we need these git hooks, you are welcome to help us out. I would add you as a collaborator etc at that point.

[dankohn]

I believe you should choose either Gitbook or Jekyll for the back-end of the website, and should use Github Pages to actually serve the HTML. I think you could make either work. Jekyll would be much easier to setup. Gitbook would also produce PDFs and eBook formats.

[dankohn]

It does seem possible to host the site on Gitbook instead of Github Pages, using the existing custom domain, as described here: https://help.gitbook.com/platform/domains.html

My hesitancy is that Github Pages is one of the most reliable hosting platforms in the world, but for this application, it probably doesn't matter.

[onebree]

@dankohn is it possible to have Gitbook fetch only certain partials from the Jekyll site? Such partials would be just markdown, and easy to translate to both formats. Maybe even have Gitbook point to a particular branch, if possible.

[dankohn]

Anything is possible, but Jekyll and Gitbook do not use identical flavors of Markdown, so this is harder than it looks. I strongly recommend picking one or the other as the back-end format.

[onebree]

@dankohn thank you for your insight. I brought Gitbook up because I am personally moving away from Jekyll (with my blog), and I like the documentation-style of it.

In regards to Markdown, I know you can specify the flavor in Jekyll, such as GFM (which Gitbook supports).

If, at the end of the day, Gitbook only provides the PDF/ebook feature, we could find an alternative route within Jekyll (or a different generator altogether). Basically, the end-user can always view the Markdown generated file in Github, and print off from there. The issue with that is Liquid syntax (which powers Jekyll) does not render nicely on Github. (It's mainly used for syntax highlighting.)

[akz92]

@onebree sorry for the really long delay to answer. I had never seen GitBook, I visited a few pages and it looks good for documentation purpose but personally I believe it isn't the best alternative for betterspecs. Using GitBook we won't need to worry about design but betterspecs design is done, I don't think it will be a problem. On top of that, the Jekyll version is almost done and it solves the main problem of the project.

[andreareginato]

Hi everyone. Next week (probably on Monday) I'll take one day off to move betterspecs.org to Github pages and to give it a new restyle. This should make changes easier for the community.

I would love to ask @onebree (which is greatly maintaining the site) to give me all the info I need, not missing any update (for what can be possible).

Thanks everyone.

[onebree]

@andreareginato Right now, @akz92 has a demo of the site in Jekyll. I have not looked at it much, however. An alternative to Jekyll/GH Pages is this, which can easily be styled with the current color scheme.

https://github.com/jeromegn/DocumentUp

It has a GH pages guide, and the v1 theme looks exactly like what we want -- a sidebar with headings/links. I even found how to remove the "Fork me on Github" banner from the final site.

Once the site is ported over to GH pages, information needs to be updated for Rails 4 and RSpec 3. This is greatly important as Rails 5 is in beta.

[akz92]

@andreareginato feel free to use any code of my port. I'll be glad to help if there's something I can do.

[onebree]

@andreareginato if you do use @akz92's port, I think it would be best to push his commits to a temp branch on github. Then he will still get credit in the commit history for his work :-)

[andreareginato]

Hi everyone.

A draft for the new version of Better Specs is up and running.

New features.

• Works on Github pages (this will simplify the contribution process)
• Responsive (works well on mobile and tablet)
• Cleaned up the whole content
• New layout (more 2016)

Todo before release

I would love to ask @onebree, @akz92 (thanks for the initial porting), @dankohn, @benoittgt and all better specs community to take some time, if possible, to close the last needed task before going online with the new version, which regards to the translations.

• Adapt all "translation pages" to the new layout (this will take some hours, but it should not be difficult)

Unluckily I'll not have the time to make them all, and I thought about asking your help.

Nice to have

There is also nice to have todo list (see below) which is not mandatory for the release, but that list some important things I guess we should take in consideration pretty soon.

• Review all guidelines (they have been written more than 3 years ago and it needs a deep polish)
• Place all translation pages in a more structured way, while maintaining todays' paths
• Better use of Markdown (if possible)
• How do we handle comments? Which could be other tools to use in order to replace Github issues.
• When reloading the page with an anchor, the correct section is not loaded

Let me know what do you think guys.
Thanks a lot for your time.

[onebree]

Overall

@andreareginato I absolutely love what you've done! I think the sidebar can remain dark, as well as code samples, but I would like to see a light page background. It adds some contrast, and is easier on the eye (all dark parts are blocked out then, not blending into the background).

Commenting

• Disqus
  • Requires a separate account, or OAuth through Facebook/Google/Twitter
  • No code formatting (that I am aware of)
  • Comments will be tied to the page, however, not to the guideline (like how you see on blogs)
• Discourse
  • Forum-format with threading, similar to how we are doing it on Github Issues
  • Can OAuth with a Github account (which clearly everyone has already)
  • Written in Ruby and is open source
• Gitter
  • Real-time discussion of issues
  • Sign in with Github account (only option?)
  • No invite required to join
• Google Groups
  • Most everyone has a Google account, or has experienced gGroups
  • Threaded style, allowing one post per guideline

Personally, I would go with Google Groups or Discourse. Either way, I can help push all existing issues to the new platform, and pretty much summarize what everyone has said.

Markdown

Edit -- Master branch uses Nanoc, while the proper gh-pages branch uses Jekyll. I've removed comments made thinking we were using Nanoc.

According to this blog post, Github is updating to Jekyll 3.0, which defaults to the Rouge gem for Markdown processing. This is great, because it has built-in support for Github flavored markdown. The Gemfile and config may need to be tweaked a bit, but I can look into that further.

Side note: how about moving to HAML? I mean, who enjoys looking at regular HTML these days?

[dankohn]

Congrats, I think the new pages look great. I would prefer to see discussion just use Github issues, as it is the easiest and most popular option.

[onebree]

@dankohn what says it is the most popular option? I mean, it was done with this repo because I assume other tools were not available, or useful, at the time of creation.

[dankohn]

@onebree Most popular in the sense that nearly all developers have a Github account, while far less have Disqus, Discourse, Gitter, etc. Note that I'm not arguing that Github issues are the most feature-rich or even necessarily the best option, just the most ubiquitous.

[onebree]

@dankohn Well you can sign into Discourse and Gitter with Github. In fact, Github is the only login option for Gitter, I think!

[andreareginato]

Hi guys. Thanks a lot for your answers.

If you guys agree I would keep this discussion to close the issues that are important to go online with the new version as soon as we can. To make this happen the issues to close are these.

• Adapt all "translation pages" to the new layout (this will take some hours, but it should not be difficult)
• When reloading the page with the anchor the page doesn't go to the right section.

We need to give a priority. When we close these issues we can move to the tech ideas you were talking about. I know it's "the dirty stuff", but this is what we need to do to move to Github pages and let anyone partecipate. This means that for the moment, we can leave actual comment system (surely can be improved), so we can focus on translations and main bugs.

Let me know what do you think

[onebree]

@andreareginato What browser were you using? On Firefox 44, I had no issue with the anchors. (That is betterspecs.org/index.html#describe, right?)

[onebree]

I get that issue as well in Chrome if I CTRL+F5. But if I visit that link directly, I am brought to the correct heading.

[onebree]

@andreareginato I just whipped this Markdown file up. It is not perfect, and has to be rendered in a test environment, but this is what the English index could look like:

https://gist.github.com/onebree/0147c9dc28c9a41d81f3

[akz92]

@andreareginato we could use an I18n translation like this: https://github.com/screeninteraction/jekyll-multiple-languages-plugin
It would make it a lot easier to maintain translations.

[andreareginato]

• @akz92 looks a great solution, we can go for it.
• @onebree at first looks great (it simplifies reading and writing). I would bring attention to the css structure, as we need to keep it coherent with actual HTML. I also should note the the actual index page (in gh-pages branch) has some consistent changes on the menu.

Let me know your thoughts

[andreareginato]

One more thing.

For one week I'll be out for work and I'll not be able to closely follow the progress of the works.

I wanted to leave you guys the task of making betterspecs 2.0 ready to go online telling you one more thing. Although many tech solutions can be applied, I would suggest to keep those minimal. I think going online with bs 2.0 using the internationalization plugin and the markdown syntax (where possible), would be a great win. Of course, these thought are made to shorten the time to go online with the new version as soon as we can, and many other improvements can be made after this.

Good work to everyone and thanks

[onebree]

@andreareginato The CSS was not maintained in the gist I sent you, as it did not have any accompanying CSS files. This is why I need to test this locally with the entire site. I will make a separate branch called "markdown" or something. I also just realized that the gist I made was based on master branch, not gh-pages.

Would you be opposed to simultaneously moving the site to HAML? This I can easily do myself, and I believe HAML (possibly with a gem) allows for Markdown syntax. (Similar to it allowing JS with the tag :javascript.) If you want to wait on this, I am okay with that -- it was just a suggestion to get two birds with one stone, and cleaning up the HTML a lot.

Nevertheless, I will be able to work on the Markdown structuring this weekend, as I am off from work Monday (15th).

Something I can do Friday/Saturday (which will be quick) is cleaning up the README and finishing the changelog.

[andreareginato]

@onebree I 'm not against HAML but we need to be sure to close this issue. Do you think using HAML will add much time on the process? If you can take care of it, and the final result is a much cleaner result, I'm in. Get in sync with @akz92 about the translations and I think you are ready to start.

Great work. Lets make it real this weekend :)

[onebree]

@andreareginato is the slack channel still around? I know I did not delete it. If possible, I can add @akz92 to it, and remove anyone who has not been around.

[andreareginato]

Feel free to use it. It's up and running

Il giorno gio 11 feb 2016, 15:32 Hunter Stevens notifications@github.com
ha scritto:

@andreareginato https://github.com/andreareginato is the slack channel
still around? I know I did not delete it. If possible, I can add @akz92
https://github.com/akz92 to it, and remove anyone who has not been
around.

—
Reply to this email directly or view it on GitHub
#153 (comment)
.

[onebree]

@akz92 Would you like to join the Slack channel? Right now, it just posts updates from github. If you are interested, please let me know which email to use.

Furthermore, I found this comment, where someone suggested using YAML for translations (@eliotsykes):

#150 (comment)

Just in case its of interest and not been discussed, putting the translations into YAML and adding betterspecs to the public projects here https://github.com/Locale (https://www.localeapp.com/) might gain some translators/maintainers.

[onebree]

@andreareginato I have updated the changelog for all changes since I became a contributor: 45cbdb6

Happy 300 commits!

[akz92]

Sure @onebree, my slack account email is aride.moulin@gmail.com.
The translation solution I proposed uses YAML too. The kind of translation service mentioned by @eliotsykes is great but also expensive. It has a 500 word limit and supports only 2 languages on the free plan. Besides that, I believe it's intended to be used in rails projects, I don't know if it's possible to use it in a Jekyll project.

[andreareginato]

@onebree Impressive job :) Really really nice!
@onebree about i18n although I didn't go in deep I would set as tool the one suggested by @akz92. I would start using it as soon as possible.

As soon as you can let me know how the porting is moving. I'm looking forward to tell the community the work you are doing. Have a nice beginning of week.

[benoittgt]

Sorry was really busy. For slack here is my email benoitjerk [at] hopsandfork dot com.

Will see on which task I can work on. Maybe : Adapt all "translation pages" to the new layout (this will take some hours, but it should not be difficult ?

[onebree]

@akz92 and @benoittgt I will add you two to Slack today. I will also open 2 issues for this project, assigning each of you to one. Just to divide this long conversation up.

@andreareginato thank you, and you are welcome. I did not get to all I wanted to this holiday weekend -- I am still figuring out the Markdown port of the site. I will worry about that before HAML. I will finish the port by the weekend. :-)

[andreareginato]

Thanks for the great work and coordination. Looking forward 👍

[pirj]

gh-pages accepted all pull requests and has diverged from master branch (that is deployed on Heroku as https://betterspecs.org) and that makes the latter severely outdated.

Examples:

1. pull betterspecs.org gh page
2. pull betterspecs.org gh page

This is a massive change, and it didn't work out to make it in one go.

Please mind switching betterspecs.org to point to GH, split this ticket into smaller chunks and work on them gradually.

[pirj]

Hi again,

RSpec style guide has recently been moved to RuboCop HQ, a common shelter for Ruby/Rails/RSpec style guides and corresponding RuboCop cops, and is actively maintained.

I was thinking about cherry-picking the practices from this great guide (both master and gh-pages, but English only) to RSpec style guide, keeping all the attribution and credits where possible.

My only concern is the legal aspect of doing so since the license is not defined for this project.
I completely missed the fact that the license is specified in the README.md on master branch as MIT and allows for derivative work.

Appreciate any feedback, and glad to discuss how to join forces on creating a better comprehensive guide that the community would benefit from.

/cc @FedeG @andreareginato @benoittgt @akz92

[benoittgt]

I think it's a very good idea :)

[pirj]

I'm not sure where it's better to ask, so I'll leave the reference to the pull request to RSpec style guide picking the rules from BetterSpecs here: rubocop/rspec-style-guide#55
It has definitely made the style guide better!

[FranklinYu]

So what’s the progress? Anything I can help?

[benoittgt]

@FranklinYu it was merged. rubocop/rspec-style-guide#55 🎉

[FranklinYu]

@benoittgt That's about https://github.com/rubocop-hq/rspec-style-guide right? How about http://www.betterspecs.org/ ? Or is RSpec Style Guide replacing Better Specs?

[pirj]

@FranklinYu The two guides always complemented each other and even intersected a bit.
Unfortunately, the maintenance was not active on either, but it's improving after migration of RSG to RuboCop HQ.

It would be easier for everyone to maintain a single guide, and even though Bettrspecs is significantly more popular (stargazed), I've started off RSG, and preferred to apply the effort on updating it, including picking all the rules from Betterspecs.

Translations were lost in transition, I hope volunteers eventually restore this miss, as it is with Ruby Style Guide, which is additionally available in ten languages.

The decision on how to proceed with this project is up to Betterspecs maintainers, whether to link to RSG and add a notice that Betterspecs are not actively maintained and migrated/superseeded/evolutioned to RSG, or to keep updating it, specifically by backporting the rules I've updated to the new realms from RSG.

Betterspecs remains a great resource, and 95% of it still applies, it has useful links to books and presentations, and again, is translated into different languages.

No matter how it goes I'd like to thank all Betterspecs contributors and maintainers for the hard work. ❤️