Unclear information in contributor FAQ regarding preliminary issue

[jmferreirab]

Describe the issue

The docs may cause confusion when a contributor wants to know if they can directly make a PR in the freecodecamp repo, or if they need to make an issue and wait until it is triaged. A discussion about the best handling of this would be greatly appreciated.

The documentation reads at faq.mdx:

I found a typo. Should I report an issue before making a pull request?

For minor typos or wording changes, you can directly open a pull request without creating an issue first. Just include enough details in the pull request description to help us review your contribution.

When I read this, I thought that for rewordings, one may directly open a pull request. Rewordings as in:

Original: A background gradient in CSS is a smooth transition between two or more colors.
Wording change: A background gradient in CSS is a way to create a smooth transition between two or more colors.

Based on previously approved PRs, there are at least two instances of wording changes that cannot be classified as typos which were approved without a preliminary issue in the repo. Details at the end.

However, the guidance provided by some members reflects that a wording change like the above should be reported and triaged in an issue before a PR is made, and that PRs without an issue are reserved only for typographical errors (misspelling, boldface, punctuation) and minor grammar fixes.

Summary

If the ruling regarding issues is, "Always make an issue for everything that's not a typo before making a PR", that's fine; and if so, can we please make the wording in the contribute site clearer?

To Reproduce

View guidance provided at the Contribute site

Expected behavior

I would like to request clearer wording about preliminary issues.

Option 1: We could have a wording that explicitly requires issues for everything that is not a typo. This means those PRs approved without preliminary issues were exceptions to the rule and should not be considered a standard for contributors.

Option 2: A wording that reflects what currently gets approved in the repo, which would entail allowing wording changes beyond typographical errors without a preliminary issue.

I believe either could be helpful to reduce guesswork when contributing.

Additional context

There are several merged PRs that have been approved without having a linked issue or preliminary issue.

freeCodeCamp/freeCodeCamp#63356
freeCodeCamp/freeCodeCamp#63326
freeCodeCamp/freeCodeCamp#63320
freeCodeCamp/freeCodeCamp#63251
freeCodeCamp/freeCodeCamp#62927

There are two that introduced wording changes beyond just typographical errors.

freeCodeCamp/freeCodeCamp#63366
freeCodeCamp/freeCodeCamp#61811

This raises a more complex question beyond the exclusion for typos:

When should a contributor make a preliminary issue, and how do we update the docs at the contribute site to clearly reflect that?

[jmferreirab]

If the consensus we reach here is to require issues for everything that's not a typo, my suggestion for the text would be:

I found a typo. Should I report an issue before making a pull request?

For minor typographical errors (ex: misspelling, punctuation), and grammar errors that do not change the substance of the original text, you can directly open a pull request without creating an issue first. Just include enough details in the pull request description to help us review your contribution.

For bigger changes, please open an issue first.

Edit 11/1: Changed wording since I'm not sure what the consensus is.

[jeremylt]

Those linked PRs are from staff. Staff are not external contributors.

This part

For minor typos or wording changes, you can directly open a pull request without creating an issue first. Just include enough details in the pull request description to help us review your contribution.

means that for minor typos or minor wordings changes external contributors can directly open a PR (the minor applies to both parts). I think your proposed wording is fine for making that obvious.

[jmferreirab]

Thank you. I'll wait for the help wanted label to make the PR with that small wording change.

[huyenltnguyen]

I think the current wording in the contributing guide is fine as is.

We don't want to police every small fix, and the guideline doesn't need to cover every case (we aren't writing a legal doc). In practice, we sometimes get PRs without an associated issue, for example:

• An upstream library author helping us update a dependency
• A user spotting a multiple-choice question with an incorrect answer

Those kinds of PRs are perfectly fine, and that would still be the case even if we changed the guideline's wording.

The point of this guideline is to help maintainers keep work organized and context clear. Creating an issue first gives us space to discuss whether a change is needed, if it fits with other work in progress, if it would have unintended effects, etc.

We expect contributors to use common sense here. If it's an obvious correction, go ahead and open a PR. If there's any doubt about whether a change is needed, open an issue first so maintainers can review it. We appreciate contributors taking the time to open an issue and let us review it, but we get frustrated when we receive PRs without an explanation or proper context.

In fact, we've seen contributors open issues to report even simple typos: https://github.com/freeCodeCamp/freeCodeCamp/issues?q=sort%3Aupdated-desc%20is%3Aissue%20state%3Aclosed%20typo.

[ilenia-magoni]

freeCodeCamp/freeCodeCamp#61811

this is the only one that is not staff, and it does not have alternative solutions, other than completely changing the question, which would be unnecessary