Creating GitHub Releases from git Tags

Julian Knight — Sun, 30 Dec 2018 21:23:20 +0000

The workflow for updating version numbers and doing git/GitHub/npm releases is far too complex to easily remember when you aren't doing it very often. This post is a reminder of the various steps.

Just a quick reminder for myself mainly.

GitHub will automatically create a release from a git tag. Having had a request for this from an issue with node-red-contrib-uibuilder, I decided that I’d better look into how to do it.

Why is everything harder than it should be!? Anyway, here is the raw workflow for committing changes to a git managed repository of code, creating a tag, pushing both master and the tag to GitHub and then publishing to npm.

# This could be minor or major instead of patch, it updates package.js
npm npm version patch -m "Patch version bump to %s"
# We might want to stage instead of committing everything at once
git commit -m "Commit message"
git push
# Create a tag to match the npm version
git tag -a v1.4.1 -m "my version 1.4.1"
git push origin --tags
# Publish to npm
npm publish

Of course, the commit and push are easier done direct from VScode.

It is annoying that I can’t link the tag to the npm version.

References

git docs 2.6 Git Basics - Tagging

List of problems and issues with Jekyll and GitHub Pages

Julian Knight — Fri, 05 Jan 2018 17:05:00 +0000

While sites generated using GitHub pages can use Jekyll to enhance them, there are some limitations and, it seems, a number of problems.

Advantages (not matched by alternatives)

The Jekyll build process runs on the GitHub back end, no need for the horrible (on Windows anyway) installation of Ruby and Jekyll. (UPDATE: See Hugo alternative for a better alternative).
GitHub provides an existing set of data about the owning organisation/person and their repos.

Sorry, can’t think of any others that aren’t matched by alternative tools.

GitHub Pages Issues

Build failures generate error messages that are worse than useless. Often not even identifying the page that the build failed on.

Hint: Connect the repo to cloundcannon.com - it will do builds and give more detailed error messages.
Looks like there may be some issues when creating pages directly from the GitHub web interface. I’ve managed to create several pages that show inconsistent metadata - I suspect they were all created via the web interface first. See Issue #6661 and this test page. You can see that the test page is not able to reference its frontmatter metadata.
Jekyll uses Kramdown to render markdown files. This does not quite match the default GFM format. While this is improving, the version used is typically behind the current one, often by a fair margin.

Minima Theme Issues

While the Minima theme is pretty good, it has a few issues of its own.

The documentation states that all you need to do to enable Disqus is to add your shortcode to _config.yml. However, this is not quite correct as Disqus in only added to posts and not to pages or collection documents, nor to the home page.
The main menu does not work quite as expected. If a page doesn’t have a title, it is ignored, not terribly safe an assumption since an xml document might have a title but shouldn’t be shown or perhaps a page needed in the menu doesn’t have/need a title. Also, it excludes collection documents which isn’t too helpful if trying to switch to collections for better content management. A better selection would be {%raw%}site.pages | concat: site.documents | where: "layout","page"{%endraw%} or something similar.

Jekyll Issues

This list is about Jekyll failings, not specific to GitHub Pages.

The sort filter does not work correctly. I have some code that includes {% for item in collection | sort: "title" %} but several entries are incorrectly sorted.
Jekyll documentation is, in my opinion, poor. Information is badly spread between pages. For example, trying to find a comprehensive list of variable filters that actually work with Jekyll is difficult. Some documentation is left up to the core documentation of the Liquid templating engine. However, while that is comprehensive, it applies to the use of Liquid in its original environment, not everything works in Jekyll.
There are too many inconsistent differences between different parts of Jekyll. For example, why are there so many differences in the schema definitions for Pages, Posts and Collection Documents?
In the page object, not all properties are set as one might expect. page.date for example is not set unless you create it manually in the frontmatter. Again, not all page properties actually apply to “Pages”, some only apply to posts or collection documents. Highly confusing.
In variable filters, the : is an unnecessary source of bugs. It serves no real purpose, a simple space would be sufficient.