Skip to content

[Triage] Instructions for assigning "good first issue" - #121

Open
AThousandShips wants to merge 1 commit into
godotengine:mainfrom
AThousandShips:first_issue
Open

AThousandShips wants to merge 1 commit into
godotengine:mainfrom
AThousandShips:first_issue

Conversation

@AThousandShips

@AThousandShips AThousandShips commented Sep 9, 2026 •

Copy link
Copy Markdown
Member

Still ironing out the last details, and waiting for the ongoing refactor before finalizing the links and structure

This is generally based on experience with new contributors and what I've seen as sources of friction with PRs

@AThousandShips AThousandShips added the enhancement New feature or request label Sep 9, 2026

@CreatedBySeb CreatedBySeb left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me! I think this type of guidance is helpful for these sort of cases where there is a significant 'feel' component since it gives an insight into what may be worth considering.

@AThousandShips

Copy link
Copy Markdown
Member Author

Will rebase and bring out of draft today or tomorrow

@rsubtil
rsubtil self-requested a review September 15, 2026 12:00
@AThousandShips AThousandShips changed the title [WIP] [Triage] Instructions for assigning "good first issue" [Triage] Instructions for assigning "good first issue" Sep 15, 2026
@AThousandShips
AThousandShips marked this pull request as ready for review September 15, 2026 14:11

@Rudolph-B Rudolph-B left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me!

@rsubtil rsubtil left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me! (Also clarifies some doubts I had about it, which is great 😌 )

@Ivorforce
Ivorforce requested a review from a team September 16, 2026 11:52
Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated
it a great fit for new contributors who want to become familiar with
the code base. It should be removed while an active PR is available, that
resolves this issue.
resolves this issue. See :ref:`good first issues <doc_good_first_issues>` for details on how

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
resolves this issue. See :ref:`good first issues <doc_good_first_issues>` for details on how
resolves this issue. See :ref:`Good first issues <doc_good_first_issues>` for details on how

I think since this is a section in the documentation, it should be capitalized to match? Without the capitalization, I would intuitively read this as being a link to a list of issues marked with "good first issue".

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't do that generally, I'd say that the rest of the sentence makes it clear what it links to, but can adjust to make it more clear, I don't think the change to capital "G" would make any difference on what it seems to link to

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps changing to "See the section on good first issues below" would be another good alternative? That way it's clear it's the documentation section, rather than actual examples of good first issues?

If you still feel the existing wording is fine, though, it's not something I feel too strongly about 😅

Comment on lines +301 to +303
- Anything :ref:`not appropriate for new contributors <doc_new_contributor_rules>`,
in particular refactors, issues that require new features to resolve, as well as stylistic changes
and "nitpicking".

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stating that "anything not appropriate for new contributors" should "never be considered good first issues" feels redundant to me. The items listed here also all feel to me like they're fairly notable, so they could be expanded upon like so:

Suggested change
- Anything :ref:`not appropriate for new contributors <doc_new_contributor_rules>`,
in particular refactors, issues that require new features to resolve, as well as stylistic changes
and "nitpicking".
- Refactors: Code in the engine is often written the way it is for a reason, and that reason may not be apparent to new contributors. A new contributor may end up breaking the underlying logic for working code, or bring it away from the Godot code base style, if they attempt to refactor it.
- Issues that require new features to resolve: As per the :ref:`new contributor rules <doc_new_contributor_rules>`, someone must have a minimum number of merged PRs before they can contribute new features.
- Stylistic changes and "nitpicking": As stated above, Godot's code base has an established style and conventions which new contributors may not be familiar with.

If you decide to try this out, feel free to work on the wording!

For a more concise list, I think having each item without the following justifications for each one would be okay. I personally like providing the reasoning for each item, but at the same time they may be fairly obvious and thus unnecessary.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to reduce the potential for duplication here by directing to a ground source for what this means, but I'll adjust it a bit. The note about refactoring is not really what is important here I'd say, the point here is that we shouldn't assign issues that are not appropriate for a new contributor this label as that isn't necessarily obvious

But I'll look at improving the wording a bit still

Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated
Comment thread development/workflows/triage/guidelines.rst Outdated

All this being said, do not worry too much about "incorrectly" assigning this label. It's not easy to evaluate how hard an issue might be to solve,
and how complicated the review process might be. Mistakes happen, don't let that stop you from assigning it.
At the same time, avoid assigning the label if you are not sure about it being appropriate. Make sure to remove it if things change.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
At the same time, avoid assigning the label if you are not sure about it being appropriate. Make sure to remove it if things change.
If things change and you realize resolving the issue will be more work than originally believed, you can remove the label.

I feel like the existing version of this line contradicts the previous lines a bit. The previous lines basically say to me, "You can assign this label even if you're not 100% sure it applies, don't worry, mistakes happen." Then, this line says (to me) "Don't assign this label if you're not 100% sure it applies".

As per my suggestion here, I'd probably end with focusing on the fact that the label can be removed if necessary, and describe how to determine if it's necessary.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still want this emphasis here, there's a difference between being overly cautious and being reckless about it, the former sentence is meant to say "if you feel reasonably certain go ahead and assign it, it's okay if it's wrong", and the latter "if you doubt it's appropriate, don't assign it"

I'll try to reword it to be more clear

@AThousandShips

Copy link
Copy Markdown
Member Author

Will take a look at the feedback tomorrow!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants