Proposal: Change CONTRIBUTING.md to have practical steps to get started #449

lenikadali commented 2026年02月27日 19:28:16 +01:00

From @aahlenst in #415:

@mfenniak wrote in #415 (comment):

I think the clarity that is needed in the process will still have people doing this, but I want them to be informed as early as possible that they're taking a risk with their time.

I agree with the objective. But I don't think that any process can fix it. (This is no criticism of the process proposed here.)

I think the problem is not the process, its stages or labels, but that people aren't set up to succeed.

CONTRIBUTING.md doesn't send me immediately to the Contribution Guide. It's literally the last link in the document.

The Contribution Guide is way to extensive for newcomers. None of the titles suggest that I can learn how to open an issue or what it is expected from me when I want to work on something.

CONTRIBUTING.md should be converted into a quick start guide for newcomers with very simple, actionable instructions.

You encountered a bug? File a problem. You want a new feature? File a problem. You want a new feature and are ready to implement it? Do X. You want want to fix a bug? Do Y. You didn't get a response? Do Z.

If somebody needs details, refer them to the appropriate section in the Contribution Guide.

CONTRIBUTING.md should also encourage discussion and iteration. There's a tendency in our industry that code is the most important thing. Nobody enjoys reviews due to the delay and rework. That results in large PR drops out of nowhere and the expectation that they should be perfect. But I want people to discuss their ideas first and send imperfect PRs. That allows iterating on ideas and come up with better solutions.

From @aahlenst in [#415](https://codeberg.org/forgejo/discussions/issues/415#issuecomment-10603226): > @mfenniak wrote in #415 (comment): > > > I think the clarity that is needed in the process will still have people doing this, but I want them to be informed as early as possible that they're taking a risk with their time. > > I agree with the objective. But I don't think that any process can fix it. (This is no criticism of the process proposed here.) > > I think the problem is not the process, its stages or labels, but that people aren't set up to succeed. > > [CONTRIBUTING.md](https://codeberg.org/forgejo/forgejo/src/commit/e811313298376005f4a96f8d0a17d5ca54b89804/CONTRIBUTING.md) doesn't send me immediately to the [Contribution Guide](https://forgejo.org/docs/next/contributor/). It's literally the last link in the document. > > The [Contribution Guide](https://forgejo.org/docs/next/contributor/) is way to extensive for newcomers. None of the titles suggest that I can learn how to open an issue or what it is expected from me when I want to work on something. > > CONTRIBUTING.md should be converted into a quick start guide for newcomers with very simple, actionable instructions. > > You encountered a bug? File a problem. You want a new feature? File a problem. You want a new feature and are ready to implement it? Do X. You want want to fix a bug? Do Y. You didn't get a response? Do Z. > > If somebody needs details, refer them to the appropriate section in the Contribution Guide. > > CONTRIBUTING.md should also encourage discussion and iteration. There's a tendency in our industry that code is the most important thing. Nobody enjoys reviews due to the delay and rework. That results in large PR drops out of nowhere and the expectation that they should be perfect. But I want people to discuss their ideas first and send imperfect PRs. That allows iterating on ideas and come up with better solutions.