DEV Community: Stefan Buck

Codeless Contributions with GitHub Issue Forms

Stefan Buck — Fri, 15 Oct 2021 19:58:11 +0000

Let’s talk about GitHub contributions and rethink them a bit. I want to start with questioning the foundation: what if we could contribute to a project without having to create a pull request? Imagine all we have to do is to create a GitHub issue. Yes, you can do that with GitHub Actions and the new GitHub Issue Forms. Let’s get to it!

What are GitHub Issue Forms?

GitHub Issue Forms are a new feature (currently in public beta). Historically, repository maintainers used issue templates to semi-enforce a structure within a free text field, but this barely did the job. Too often people just deleted sections or didn’t fill them out.

Now, with Issue Forms, gathering information is significantly more effective. A form is described in YAML.

name: Bug Report
description: Tell us what did not work
labels: [bug]
body:
- type: textarea
  id: description
  attributes:
    label: What happened?
  validations:
    required: true
- type: dropdown
  id: version
  attributes:
    label: Affected version
    options:
    - 1.0
    - 2.0
    - All of them

Issue Form configuration with two input types

The following input types are supported: textarea, input, dropdown and checkboxes. We can even mark certain inputs as required. The rendered issue template looks like this:

Beyond filing bugs

Let us take things up a notch, and see how we can use the power of Issue Forms to go beyond filing bug reports and feature requests.

We learned that issues created through Issue Forms have a predictable structure. This enables all sorts of great automation. To simplify integrating with contents of Issue Forms, I wrote the GitHub Issue Parser Action that parses the issue body and outputs the content in a JSON format. Issues created using the Issue Form from above will create such a JSON output:

{
  "description": "Process keep running after closing it",
  "version": "1.0"
}

Issue Form Parser output

From here we can do whatever we want with the data. For example, we could insert this bug report in a database, or make a commit to the same or another repository. It helps to think about GitHub Actions as compute that run GitHub's infrastructure triggered by events like issue:opened; only your imagination is the limit.

Example: Codeless contribution

I maintain a list of awesome browser extensions for GitHub. Every now and then I get a pull request to add a new extension to the list. Dealing with the pull request is sometimes a bit of a pain for both the contributor and me. Especially when the contribution guidelines are not met. Applying what we have learned with Issue Forms, we can simplify this process to one simple step.

Rather than having people to fork, pull, commit and create a pull request, they now can just create an issue using the "Submit extension" Issue Form. This form will require a bunch of information about the extension such as name, description, links, etc. As a last step the user clicks submit and the issue is created, waiting to be accepted.

A "merge" can be instantiated by applying the merge label. This will trigger a GitHub Workflow that will convert the issue into a code contribution.

Let's break down the steps:

A new issue has been created using the "Submit extension" Issue Form.
A maintainer reviews and approves the issue by adding the merge label
A GitHub Workflow that listens for labeled issue event runs. 3.1. To avoid conflicts with other issues, a step condition checks whether the issue is labeled with merge
The GitHub Issue Parser runs and outputs the issue body in JSON format.
A Node.js script reads that JSON, stores the data in a data.json and generates the readme.md file. 5.1 During this step, additional data like installation count, GitHub stars are fetched to enhance the readme.
The changed readme.md and data.json files are pushed to the repository.
The issue is closed with a comment.

I call this a "codeless contribution". As promised early it allows contributions to a project without having to create a pull request!

Pros

Much faster and easier to contribute to a project.
Really low barrier to entry. No understanding of the GitHub Fork & Pull Request Workflow is needed.
The repository's contribution guidelines can be enforced.
Validation and feedback on the issue contribution can be implemented
No merge conflicts as issues and resulting changes are generated and committed sequentially.
Fixing provided information is as simple as updating the issue.
The contribution can be enhanced during the "merge" process. In the example, live data such as GitHub stars was dynamically updated on merge.
Contributions can be stored within the repository to allow further processing in the future.

Cons

Issue creator does not automatically get attributed as a contributor.
Does not work for more complex contribution types like code changes.

Example: Pizza order

If you ever wanted to order a pizza through GitHub, now's your chance. After the order has been placed, a GitHub Action picks up the issue, does the parsing using GitHub Issue Parser, some validation, and then creates a new commit with the order by updating the readme. Give it a try and see how it works.

Example: Repository templates

In the Repository Templates Meets GitHub Actions blog post, I talk about how GitHub Actions can be used to create a repository template with templated values. This is another great use case for codeless contributions. After creating a repository from a repository template (which is effectively just a task to copy) filling an issue within this new repository is substituting the template values with the actual values from the issue.

Example: Show preparation

Gregor Martynus aka gr2m is using GitHub Issue Parser, to prepare his show helpdesk where he is answering all your GitHub API/automation questions live on Twitch.

Example: Advanced validation

At the time of writing, Issue Forms do not support any custom validation. However, using GitHub Issue Parser enables you to add any kind of validation by processing the issue on the issue:opened event.

The options for codeless contribution are endless. There is no need to force contributors into pull request workflow. Let’s all make everyone’s life easier, with codeless contributions through Issue Forms!

Are you interested in this concept? Want to discuss further? Let’s continue the conversation on Twitter.

10 Tips to Get Faster Code Reviews

Stefan Buck — Tue, 01 Jun 2021 22:01:01 +0000

Code reviews can help to improve the quality of code, reduce technical debt, and they are a great way to spread knowledge about the past, present, and future of a software project. The only problem is that code reviews will become your bottleneck. Here's what you can do to help others to review your changes much easier and faster.

1. Review’ pull requests of others

From my experience doing code reviews for over a decade, this is probably the most effective way to get your stuff reviewed quickly. It’s also a great way to level-up your understanding of the codebase and familiarize yourself with new methods from other developers.

2. Be your first reviewer

Nothing is more annoying than spotting spelling mistakes (my specialty) and other obvious mistakes in a code review. Before requesting a code review, review your own pull request with fresh eyes. This is also a good time to apply the next tip.

3. Add comments on your own pull request

Doing a proper code review takes time. Therefore we should make this a pleasant experience for everybody. Use review comments to guide the reviewer through your changes. Think about what may be unclear to them and provide additional context.

4. A well-drafted description

Do not copy the JIRA ticket description. Instead link to the ticket, (this can be automated using Pull Request Badge) and write a description for your peers. For visual changes, it’s helpful to include screenshots (before, after) or record a quick video. Adding links to visuals, mockups also help reviewers to get a better understanding of your change.

5. Specify the area you want feedback on

Specify the areas you want feedback on. Are you concerned about a specific line of code? Are you looking for alternatives? Adding this background helps the reviewer to provide more effective feedback.

6. Credit

Post any interesting findings which you came across while researching for a solution, such as documentation or blog posts. Also, don't forget to include a link to the Stack Overflow posts where you copied the code snippets from.

7. Automate nitpicking comments

When someone asks for trivial changes, consider automating such feedback into your CI. Tools like Danger or ESLint can help. Btw, writing a custom ESlint plugin is not that complicated.

8. Split your pull request

Don’t be afraid to put the extra time into splitting up your work, it's worth it. For example, if your change includes a refactor, create a separate pull request just for that. Not only does it make your main pull request smaller, but it also allows others to enjoy your improvements without being blocked by the other change. Also, it will go into production earlier, and therefore provide confidence in the change.

9. Close pull request

If you took the wrong route, close the Pull Request and open a new one. Point to the original and explain why one approach was chosen over another. Your future self will appreciate that over a force push.

10. Gangsta merge

Let’s end with a controversial one: Not every Pull Request needs code review. Sometimes it's totally legit (in my opinion) to skip the formal code review process if

a super trivial change is being made, such as updating an image
obvious spelling mistakes are being fixed
a hotfix needs to be applied to a production as soon as possible to avoid further damage.

Do you have other tips on how to improve the code review process? Share it with me — I’m @buckstefan on Twitter.

Five Essential Tools I Have Used for Years

Stefan Buck — Mon, 17 Aug 2020 17:08:32 +0000

Lots of tools come and go, but some become a crucial part of our workflow. In this post I’m going to share the five essential tools that I have used for years.

1. SCM Breeze

If I have to pick one single tool, it would be SCM Breeze. It’s a collection of shortcuts that makes it much easier to interact with the Git command line and other system commands. With SCM Breeze I no longer have to type paths for commands such as git add ./random.txt. I can simply type gs to get a list of all recently modified files. In this list, each file gets a number next to it. Now I can write ga 1 to add the first file to my staging list. If I need to add multiple files I can pass a range like ga 1-3 or even use a combination like ga 1-3 6 9.

To switch branches, I type gb to get a list of all branches, followed by gco 3 to check out the third branch listed in the previous operation.

Did you know that you can go back and forth between branches using a dash? Just type git checkout - or the SCM Breeze way gco -. This is not a feature of SCM Breeze and works with cd too.

Another super handy feature is the ll shortcut. This calls ls -al under the hood, but adds a number for each entry as well. This allows me to perform other commands like rm 1-3 on top of that, super neat!

Why I use it

Git is the tool I use every day. SCM Breeze is an essential tool to speed up my Git workflow. It’s very easy to use, integrates smoothly into my workflow, works with other system commands, and is overall a huge time-saver. Highly recommended!

2. Fasd

Fasd is a tool to access files and directories much quicker and more efficiently. Fasd records all files and directories I have accessed in the background and ranks them by “frecency” (a combination of the words “frequency” and “recency“). Then I can use Fasd to jump to directories by just a few key identifying characters. For example to access ~/user/stefan/code/octolinker all I have to write is z octo.

Why I use it

In the past, I set up bash aliases for every single project, so I could switch between projects very quickly. Now with Fasd it just works and I don’t have to maintain a list of aliases anymore.

3. Prefix commit message

In my day job, we prefix every single commit with the related JIRA ticket number. I quickly got bored of typing the JIRA ticket number over and over again. I utilized the prepare-commit-msg git hook to check the current branch name and automatically prefix the commit message with this JIRA ticket number. The JIRA commit message git hook script is available as a gist.

Why I use it

Because I’m lazy! And I like to automate boring recurring tasks. I can’t imagine prefixing my commits by hand anymore. In addition, this pattern works well with Pull Request Badge, a GitHub App I wrote primarily for myself.

If you want to learn more about Pull Request Badge, you can check out my other post how to automatically add links to a pull request.

4. Giphy Capture

I often add an image or a GIFs to a pull request description to help explain a visual change. I've tried many different apps, but Giphy Capture is the best way to create gifs!

Why I use it

The ability to trim and cut the recorded GIF straight in Giphy Capture is the main reason why I used it. Apart from that, the app is simple and easy to use.

5. OctoLinker

OctoLinker is a browser extension for GitHub which turns language-specific statements like include, require or import into links. I wrote the first version in 2013. It’s still actively maintained, supports over 20 languages / tools, and is trusted by over 25000 developers.

Why I use it

I use OctoLinker primarily for reviewing Pull Requests. OctoLinker makes it easy to discover unknown dependencies and allows me to jump to relative files with a single click. It integrates smoothly with the GitHub UI and makes reviewing pull requests faster and better. Give it a try!

I love all five tools — they save me a lot of time and I use them every day! I'd love to hear your favorite productivity tools.