Hacktoberfest is now opt-in and on GitHub and GitLab. Make sure you have opted in.⌗

PRs for Hacktoberfest count if:

  • Submitted during the month of October AND
  • Submitted in a public repo AND
    • The PR is on either GitHub or GitLab AND
    • The PR is labelled as hacktoberfest-accepted by a maintainer OR
    • Submitted in a repo with the hacktoberfest topic AND
      • The PR is merged OR
      • The PR has been approved

Not familiar with repository topics? I wasn’t, either.

  • Go to your repo and click “About”, then add any useful topics, along with hacktoberfest if you want contributors. giving your repo topics

Making a good Hacktoberfest issue:⌗

The secret to getting pull requests from Hacktoberfest participants is trying to put yourself in the shoes of a first time contributor. A first-time contributor may have some of these characteristics:

  • This may be their first time using Github, or their first time using source control out of a work or school context.
  • They have zero to many years of experience in this programming language.
  • They may have previously worked on projects alone or in very small groups, always starting from the beginning of the project.
  • They have limited free time, and are using Hacktoberfest as a trial run in spending free time working on open source code.
  • They like a free digital badge that unlocks a new level and customization of the badge with each of their accepted pull/merge requests.

Keeping aware of these characteristics, we want to have as little friction as possible between creating an issue, having a stranger read that issue, decide to work on the project, bring down your repo and get it to run, make the needed changes, and put in a pull request, have their code reviewed, and get those changes accepted.

Introduce the part of the program that needs attention and how it works in general.⌗

If someone has never seen your repo before, they probably don’t know how your stuff works. Help them out. Give a general overview of what is currently happening in the application.

Use a Descriptive Title for Easy to Understand Directions⌗

Many folks won’t open the issue if they don’t think they can help you with the solution.

Define the problem or enhancement you want.⌗

Make a permalink to the line numbers, or refer to particular parts of code that are relevant. Here is how to create a permalink to a line or lines of code that can be used inside of an issue: https://help.github.com/en/articles/creating-a-permanent-link-to-a-code-snippet You can do the normal user story stuff here. Example: As a someone, I want a thing so that I can do something.

When it’s useful to do so, include screenshots or images.⌗

GitHub makes it really easy to add images to your issues, and a picture can be very descriptive, so consider using a screenshot to help explain what you’re looking for.

Gifs and diagrams can be very helpful, too! You can use free software like LICEcap or ScreenToGif to make these relatively easily. example

Split work into small chunks.⌗

One big hurdle that keeps people from putting in that first pull request is looking at the issue, not knowing where to start, then closing everything without making any contributions. Splitting up work into smaller, but still meaningful, bits. Create issues that fit between “Add your name to a text file” and “Reinvent quantum computing and create order from chaos”.

Do you know the lines of code you want changed? Include them with a code snippet!⌗

In 2017, GitHub added the ability to embed code snippets into your issues. To include your code, you’re going to need to create a permanent link to a code snippet, and GitHub has put some documentation on how to do so here. Generally, if you go to the code in question on the GitHub website, there’s a little context menu on the left side that lets you select the code and make a permalink. You can also create an issue directly from this menu, if you haven’t already created the issue. Giving the additional code context can really help get someone more familiar with the code in your project.

Consider making your repo “ready to code”⌗

There are a variety of services that allow you to open your repo inside of a container with an online IDE, which greatly I’ve had good luck using GitPod to do so on some of my repos, but other alternatives exist, such as Glitch and the upcoming GitHub Codespaces, so feel free to make your own decisions based on programming language or other factors.

Give suggestions on a possible path to pursue to accomplish the task.⌗

Consider giving some architectural advice on the sort of change you’re looking to see.

Tags, Tags, Tags!⌗

There are websites that help people find Hacktoberfest tickets to do, and many of them allow the potential coder to filter by tags/labels. If you want your ticket to be found, use tags in your labels section that will make your issues appear in these lists! Here are some tags to consider using in your issue labels:

  • up-for-grabs
  • first-timers-only
  • trivial
  • beginner
  • “easy pick”
  • “good first issue”
  • “help wanted”
  • newcomers
  • jump-in
  • easy
  • documentation
  • tests

Aim to be truthful with your tags. Don’t tag everything with trivial if you don’t think it will be.

Be communicative when people offer to help.⌗

Folks will often reach out in the issue comments before getting into the code. Be supportive.

Was their PR helpful? Add the hacktoberfest-accepted tag!⌗

Did you appreciate their work? Help them get credit for it by either merging the PR, adding the hacktoberfest-accepted tag, or both! hacktoberfest-accepted

Use templates and guidelines to help communicate what you expect.⌗

CONTRIBUTING.md files⌗

The standard way to provide guidelines on contributions to your repository is to create a CONTRIBUTING.md file. That file should contain your expectations for contributors, and any background information that those contributors should go through if they wish to participate in your repository. What should you put in it? Embedded Artistry has a good checklist and Mozilla has an article about how to create one. Borrowing is the sincerest form of flattery, so you could always look at the more than 7 million references to CONTRIBUTING.md on GitHub.

Pull Request templates⌗

Do you want something included in your pull requests? Create a template, and you can auto-populate your pull request with the information that you’re looking for. Github has some good documentation about it, but there are a few rules of thumb.

  • If you want the template to be easily viewable, make it in pull_request_template.md or docs/pull_request_template.md
  • If you want it to be in a hidden directory, make it in .github/pull_request_template.md
  • To create multiple pull request templates, get ready to read some more documentation, as that seems to be a bit more complicated.