This is a
playground to test code. It runs a full
Node.js environment and already has all of
npm’s 400,000 packages pre-installed, including
good-first-issue with all
npm packages installed. Try it out:
good-first-issue lists no main file and has no index.js, so it can't be directly required. If this is a mistake, please let us know. It may however contain internal files that you can require manually:
This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.
A CLI for finding issues labeled with Good First Issue to help lower the barrier to contributing to open source projects.
To use Good First Issue, you'll need to have a few things installed:
npm i -g npm
This module is an interactive CLI. If you're looking for a module to use in an application, check out libgfi.
The suggested usage is via npx:
npx good-first-issue [project] # temporarily install and run the module, optionally passing `project`
Alternatively, you could absolutely install good-first-issue as a global module:
npm i -g good-first-issue # install globally good-first issue # call the CLI
good-first-issue: open up the interactive project selection tool.
good-first-issue [project]: you can pass in a name from the list of projects which is a curated list of projects that have been verified to have good-first-issues.
good-first-issue [GitHub organization or user]: similar to
[project]but will search any GitHub organization or user that exists for issues labeled with "Good First Issue".
good-first-issue [GitHub organization or user]/[repo]: similar to
[project], but will search a specific repository on GitHub within the organization for issues labeled with "Good First Issue".
-o, --open- open in browser
-f, --first- Return first/top issue
good-first-issue is still in an early state. I wanted to get
good-first-issue node out the door, but have some other things I'm planning on implementing. Here's a list:
good-first-issueis run without a sub command
Feeling Luckyto be better about picking a random issue
If you'd like to help with any of these, feel free to submit a PR or ask how you can help 🤗
The table of projects which are currently supported.| Order | Name | Project `
If you'd like to add a new project to
good-first-issue, you're more than welcome to submit a PR! There are a few components you'll need to submit:
<project>as a property of
projectsin the correct alphabetical position with an object that includes a
description, and a
q(representing the GitHub search query).
README.md by running
npm run markdown
You can pull your queries directly from a standard GitHub search! If you want to build something a bit more complex, you can use the advanced search tool if you want to build more specific custom queries: https://github.com/search/advanced
As a CLI,
good-first-issue uses the Commander.js CLI framework. If you want to better understand how our CLI is built, commander.js is pretty well documented. Also used are Chalk for terminal coloring and boxen to simplify the output container implementation.
Good First Issue follows a relatively strict release process intended to ensure the spice flows.
|Major (x.x.x)||Breaking changes and non-trivial upgrades||Ensuring that end-users can rely on Good First Issue not breaking however they're consuming it|
|Minor (x.x.x)||Project additions, other feature additions||Following the SemVer standard, project additions and feature additions are backwards-compatible enhancements. We generally try to ship one addition per Minor.|
|Patch (x.x.x)||Bug fixes, minor enhancements to metadata and content||Tiny, hardly visible fixes to improve UX/DX or fix the module|
We use both GitHub Labels and Milestones to track releases. Since project additions count as a minor release, we prefer to space those out and ship them individually rather than shipping many at once. This pace may be revised later, but for now, it introduces the need for a release queue and setting things up to be released ahead of them actually being released.
Once a PR is ready to be released, a milestone will be added that correlates to the SemVer version it will be released in. Ideally this will eventually be used for changelog tracking but for now it's just a good way to keep organized. To keep things tidy, once a new version has shipped the milestone will be closed out.
Prior to each release, whoever is releasing should be testing the release locally to ensure that the code is working as expected. This would include either running
npm i -g or
npm link in the PR branch and then testing whatever the PR is adding. Ensuring the experience isn't broken is vital.
It is worth noting that we limit the file we publish to npm with the
files property in
package.json. This property prevents code that's not explicitly listed from being shipped. We have had a situation where local testing and the published module differed because a PR was merged that added needed code in a directory that wasn't included. So, what works on your machine may not work for the end user.
To test locally, using the modules tests with
npm test and trying out a few different commands (like the selector, a specific project, a failed project, and so on) is reccomended. For example:
npm i -g # This assumes your current working directory is the module's directory good-first-issue # run the interactive CLI good-first-issue react # test the react project good-first-issue node # test the Node.js project good-first-issue github # test the GitHub organization, `github` good-first-issue github/semantic # test the GitHub repo, `github/semantic` good-first-issue thisisntarealprojectorgithuborg
If you are interested in fixing issues and contributing directly to the code base, please see the document CONTRIBUTING.md