ShinyCMS

Today I merged PR #661 - Did Somebody Say Documentation?

The highlights of this PR are:

• Each major feature and each plugin now has its own Markdown documentation file in the /docs folder
• The new ShinyCMS documentation website is generated from the files in /docs, using MkDocs

The docs website is hosted on GitHub Pages, which is pretty straightforward to set up and keep updated with MkDocs. When I run 'mkdocs build' MkDocs generates a HTML version of each of my Markdown docs (applying my chosen theme at the same time), and puts them all in the /site directory. When I run 'mkdocs gh-deploy' it pushes the contents of that directory to the special gh-pages branch that GitHub Pages serves the site from.

The only fiddly bit was preventing CircleCI from trying to run my tests on that gh-pages branch, as they would fail spectacularly on account of it having no actual code in it. The solution I went for in the end was to put a minimal 'do nothing' CircleCI config in /site; MkDocs kindly leaves this in place when I run 'mkdocs build', and then pushes it up along with the rest when I run 'mkdocs gh-deploy'.

I got a Google alert today letting me know that GitHub had automatically created this page encouraging people, especially less experienced people, to get involved with the ShinyCMS-ruby project - triggered by my tagging a few issues as 'good first issue'.

This made me wonder if there was anything I could do to further help and encourage anybody who's thinking about picking up one of those issues, but maybe isn't quite confident in doing so. I've always admired the way the Dreamwidth project brings new people into open source development and gives them a really positive start - I don't imagine I'll be getting quite as much interest as them :-p but I'd like to do whatever I can if anybody out there is interested. I was helped by the community on freenode a huge amount when I started out many years ago and I'm always looking for ways to pay that forward! In my day job I spent most of the last four years leading a team of 6-8 developers, and one of my favourite things about that role has been mentoring people who are just starting out in their careers. I'd love to use that experience to help people who are taking their first steps into the open source community. :)

So, tl,dr; if you're new to programming, and you'd like to try to tackle one of the issues on this project, but you're not quite sure whether to go for it - please get in touch. I will be happy to help you in any way I can - whether that's talking the issue through in more detail so you're sure you understand it, helping you think about how to approach the problem, pair coding with you to fix it together, or any other way I can help - whatever will make you feel comfortable to give it a go!

Today is the official first birthday of this project!

(I actually started a few days before October 1st last year, but I've decided that running 'rails new ShinyCMS' and then trying to fix all the rubocop errors in the Rails boilerplate don't count as 'starting' for purposes of having a nice neat birthday date) :)

I'm pretty pleased with how it's going so far. Although initially I wish I'd realised this anniversary was coming up a bit sooner, as I would have tried to knock a few more things off of the list of "features the Perl version has and the Ruby version doesn't (yet)". Instead I've been doing a bunch of refactoring lately, and actually I have zero regrets about that - one of the great things about this project is that I'm getting to refactor a lot, and it's made a significant difference to how happy I am with the system - both at a zoomed-in and zoomed-out level.

Today I replaced most of the Faker calls in the tests with CultureSeries.culture_ship, for great Banksian joy :)

Although I did this purely for the geeky love of the Culture books, it did actually flush out a few flaky tests - ship names containing apostrophes tended to break any tests using the 'include' matcher. I'm changing those over to has_css as I notice them, which escapes the apostrophe appropriately, and is a more precise test too, so double-win there.

Now I have to go read Player of Games again. :D

Added basic tracking of web stats (powered by Ahoy). There's not much in the way of output yet, but they're getting stored in the database now.

Hopefully, once this feature-set is fleshed out a bit more, it will allow most sites to get by without using Google Analytics, which should simplify their cookie permission requirements a fair bit.

Today I added email validation in models, using the email_address gem. Very straight-forward integration with ActiveRecord - it provides a validator, so it really just plugs straight in with zero effort. I've configured it to skip MX checks when my tests are running, I think that was the only thing I had to tweak.

Today's PR adds a News section to the CMS. This is extremely similar code to the blog feature (minus the unfinished multi-blog stuff), and at some point I wonder if there's scope for using the same code to run both sections - or at least abstracting a lot of the common functionality - but for now, a clean copy and 'rebranding' will do...

Today I added reCAPTCHA to the user registration process. This included doing some refactoring of the existing reCAPTCHA protection on comments, to make some of that code more re-usale.

I also added MJML support, and comment notifications.

The comment notifications go out to the owner of the site (can be configured on/off), the author of the content being commented on (if it has an author), and (in the case of not-top-level comments) the author of the comment being replied to, if we have an email address for them.

Today I merged the first chunk of work on discussions / comment threads.

As in the original ShinyCMS, the comment threads (and sub-threads) are fully nested, so you can easily tell what's a second/third/etc level reply and see who is talking to who.

To get the nested comments to display with the correct indentation at each level requires recursion*. Understanding recursion is nearing the limit of how clever I get on a good day, so in the past I have occasionally regretted writing this feature when I've had to work on it on a less good day ;) Not as much as I'd regret having written a comments feature with Facebook-style single-level nesting though :)

I added some new demo data (and updated some of the existing demo data) so that all of the current features are covered again.

The reason for including the demo data, and making sure it covers all the features, is so that anybody who's curious can install a dev copy of ShinyCMS locally or on a free Heroku set-up, load the demo data, and immediately play with all of the features of the CMS... without having to do a bunch of boring data entry work first.