release-with-changelog: A superior GitHub action to manage your releases

Laxman — Sat, 12 Sep 2020 07:11:27 +0000

What the hell are you talking about?

There are these core actions maintained by GitHub, under the @actions/... scope, that houses actions which automate common tedious tasks like posting output of a build, creating releases, publishing your npm modules etc.

But these actions are not that powerful per se, they only provide the most generic ways for going about with performing an action.

For example, if you wanted to automate creating a release on pushing some tags, which also contains a body of changelog commits, you can not, you are stuck with the default static input that @actions/create-release provides. This was a real requirement for us. You have to build on top of it.

Out of this necessity was born release-with-changelog, a GitHub action to automate your releases without having to worry about manually generating changelogs for every release you make.

This action takes a list of commits between the current tag and the last available tag, and uses that as body when creating releases, it's as simple as that. Not quite though, there are a little details I ignored to mention here as they require their own in depth explanation. If you want to dig more into the details, there's no other place than the self explaining code to look at 😉.

How do I use this?

You can find a sample workflow snippet in the readme or look at how some other (famous 👏) repository use this action in production here.

jobs:
  Release:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
    - uses: notlmn/release-with-changelog@v2
      with:
        header: '### Changelog'
        footer: 'Custom footer'
        include-hash: true
        include-range: true
        token: ${{ secrets.GITHUB_TOKEN }}

It's as simple as that!

You can find what these options are and what they do in a bit more detail here.

The documentation is a bit rough on the edges, so beware, but please go ahead and see if this helps you in your open-source projects.

I see, is anyone using this already?

Yes! See how some existing open-source projects are using this extension:

Refined GitHub: A browser extension with more than 12k stars uses this extension to automate its releases, and helps its users notified on new features.
browser-extension-template: A GitHub template to help you get started with building your first browser extension, also including this action to automate releases.

Shameless plug: Read how I ended up creating the later project in my previous post.

Credits where it is due

Kudos to the awesome @fregante for helping me out crushing bugs and adding features to the action. ❤

Help us improve it

We're currently working on adding features like template for changelog, excluding commits from changelog, and more.

Do you like it? Do you hate it? Please feel free to let us know the same in comments or opening issues on the repository. If you have any ideas, reach out to me using comments, twitter, or any other creative way you could think of. I promise I won't bite.

Writing a Template for Browser Extensions

Laxman — Sat, 23 May 2020 07:30:27 +0000

TL;DR: This is blog post is on how I ended up writing a GitHub template for creating browser extensions, with experience from other browser extension I've worked on, you can find it at https://github.com/notlmn/browser-extension-template/

I started working on open-source software sometime around 2016, watching Supercharged (RIP) on YouTube and making little tweaks on their repository, and also making a copy of my own. Man, those fun times.

And sometime around 2017, I found the now-famous browser extension Refined GitHub by Sindre Sorhus, which by then was in it's initial stages, and I immediately fell in love with it 😍. So, I started contributing to it, suggesting changes, implementing features suggested by other users, editing documentation, or simply triaging issues. I mean that's how one gets into open-source, even small changes like styling documentation could go a long way.

Later in 2018 I found out that Notifier for GitHub (NfG), another browser extension by Sindre, is looking for maintainers. My prior experience on Refined GitHub (RGH) helped me become a maintainer on that project, which even though is not as active as Refined GitHub, has seen a lot of changes and features added over the years.

And again, my contributions to these extensions led me to an invitation to become a collaborator on RGH. Even though my involvement on RGH has been a little hands-off, I was still contributing to it. And I really wanted NfG to be a lot more like RGH, in terms of directory structure, dependencies, and automatic deployments to extension stores so that we have a structured setup for easily managing them. At this point, most of this was achieved by simple copy-pasting code between them, as they had many shared parts.

At the same point GitHub released a new feature called template repositories, which if you do not yet know is similar to forking a repository but the source and fork are loosely related and removes most of the other annoyances like allowing the clone to be made private.

Anyway, with many people starting to create browser extensions and being made open-source, I really wanted something similar to HTML5 Boilerplate but for creating browser extensions. Even though what I wanted to create was a entirely different, the new GitHub template feature helped spark the idea.

And that's how I ended up creating browser-extension-template. The extension borrows a lot of best-practices, with tools and technologies required for building browser extensions including the following features.

Included polyfill for cross-browser compatibility.
Auto-syncing setup for syncing user options provided by browsers.
Auto-publishing to extension stores using CRON jobs and weekly tagged releases.
Extensive documentation on how to configure it (Webpack, css extraction, and even setting up Typescript).

The project also includes a sample browser extension that makes use of all of the features mentioned above.

“This extension template is heavily inspired by refined-github, notifier-for-github, and hide-files-on-github browser extensions. You can always refer to these browser extensions' source code if you find anything confusing on how to create a new extension.”

— from browser-extension-template readme

As mentioned in the readme, the extension borrows a lot from other browser extensions, and some of these features have also been backported to some of these extensions.

The project is almost a year old now, released under CC-0. If you are interested in building browser extensions, learning how they work, or even contribute to one, take a look at browser-extension-template.

If you like using browser extensions, also please take a look at my other project copy-as-markdown, and also the above mentioned projects refined-github, and notifier-for-github.