# What makes a good first issue on GitHub?

`good first issue` or `contributor friendly` are two labels that usually signify that the task at hand is a good entry into the project for internal as well as external (community) contributors. In this short write-up I'd like to share my experience when it comes to dealing with such issues or creating them which I had the pleasure of doing in multiple OSS projects I contributed to over the years.

## Should the issue be triaged beforehand?

Yes, it most definitely should, provided that it is a bug. If we're talking enhancements such as improved docs, then triaging is redundant as everyone has a good idea of what is required to be done.

At the very least, a `good first issue` should have the source of the problem narrowed down enough to ensure that it is self-contained enough for a newcomer to tackle.

#### Good examples

* [ziglang/zig#4583](https://github.com/ziglang/zig/issues/4583) -- Here, the precise spot in the codebase is pointed at, and a hint at where the solution to the problem might be found, i.e., adding a simple XML parser which parses the contents of `SystemVersion.plist` and all done within the `.macosx => { ... }` block in `lib/std/zig/system.zig` at line 227.

* [bytecodealliance/cap-std#85](https://github.com/bytecodealliance/cap-std/issues/85) -- Here, a hint at the solution is provided by stating that closing this issue amounts to having a peek at Rust's libstd sources, and working out the changes introduced in [rust-lang/rust#74606](https://github.com/rust-lang/rust/pull/74606), and then backporting the logic into the project at hand.

#### Bad examples

* [enarx/enarx-keepldr#183](https://github.com/enarx/enarx-keepldr/issues/183) -- This issue is not suitable to become a `good-first-issue` since requires the contributor to know where in the code it refers to, and requires some deeper domain specific knowledge, in this case, about quote generation for SGX attestation.

* [ziglang/zig#6044](https://github.com/ziglang/zig/issues/6044) -- This issue touches upon many components within the lang's standard library, and requires some deeper knowledge about DOS vs NT namespaces, and how they differ.

In my opinion, the good examples above require very little mentoring since they are pretty well contained and have really good descriptions with pointers at a potential solution. The bad examples above could be made into `good first issue`s provided some mentoring was available and perhaps the descriptions expanded upon, with links to relevant self-study about the problem space provided.

## What about meta-issues?

Sometimes it might make sense to mark a larger, meta issue as `contributor friendly`. Usually, in such cases, the meta issue will comprise of several smaller actable chunks. Good examples that come to mind are:

* [bytecodealliance/wasmtime#1272](https://github.com/bytecodealliance/wasmtime/issues/1272) -- This large meta issue provides an extensive list of spots where the documentation should be expanded upon. Contributors can then and report their progress directly in this issue, and coordinate with the project maintainers and other contributors.

* [enarx/enarx-keepldr#9](https://github.com/enarx/enarx-keepldr/issues/9) -- While this meta issue doesn't deal with expanding on docs, it does gather together a list of modules which are missing tests. In fact, I'd argue that having a meta issue that pulls together spots which could benefit from more testing are not only very valuable for the project at hand, but also for the contributor which will inevitably have to dig in into the codebase to understand the pieces that require further testing.