Codeless Contributions with GitHub Issue Forms

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:

1. A new issue has been created using the "Submit extension" Issue Form.
2. A maintainer reviews and approves the issue by adding the merge label
3. 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
4. The GitHub Issue Parser runs and outputs the issue body in JSON format.
5. 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.
6. The changed readme.md and data.json files are pushed to the repository.
7. 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.