How should we improve Contributing.md?

Question

How should we improve Contributing.md?

Opened this issue 4 days ago · 7 comments

We've had a recent wave of issues and pull requests that feels to me like it's not in the spirit of improving this project, rather something completely random or a change that's just for the sake of change.

Here's some examples
Issues

Pull requests

I'm wondering if improving our Contributing.md can improve this.

Maybe details like

Check for help wanted label before starting on a issue
Make sure maintainers confirm before making changes to Readme
If you're submitting an issue, think about how this improves this project. Explain it in the issue

If you have suggestions on improving Contributing.md, please comment below, let's discuss and decide how to improve it

Answer 1 · 2025-11-03T23:00:11.000Z

Hey @Roshanjossey,
for me it looks like we're mixing Contributing.md with a list of translators. I think we should add translators in a specific file.
Contributing.md should mention details how to actually make first contribution. To explain terms like pull request, review, merge, conflict, issue, etc. It should be referenced somehow in the main README.md in order to give better overview to first-time users how to properly use repository and git.
This is just my opinion, so I'm wondering what @Roshanjossey, @Sharl0tteIsTaken & @Esh07 think about this.

Answer 2 · 2025-11-04T13:30:43.000Z

Hello @Roshanjossey,

I stumble upon this repository when I needed a place to practice how to use and navigate Git. To me, the structure of this repository is a bit different then other repo (every repo is different tbh), nonetheless it's easy to keep up with the tutorial.
I'm new to GitHub, I don't have an expectation of what is supposed to be on Contributing.md, other repos like numpy, matplotlib, scipy have guidelines on how to contribute to their repo, I think first contributions have a similar approach.

These issues and PRs include: someone adding their name to the wrong file, changing for the sake of change, adding redundant section. I think these type of actions is inevitable in the age of AI (I'm not saying that all these were the result of AI). I think best we can do is to use a bot to automatically tag someone if any files other than Contributors.md are modified, just like in #101727. Or is the bot not in use now?
If we really want to nitpick, I think Contributing.md and Contributors.md aren't really that self-explanatory. The only difference between them is the suffix, maybe it's hard to differentiate for someone at first glance? Has someone said something about this before?

I think specify that issues with tag `help wanted` are welcoming help from everyone, and please prioritize to participate there (or something like this) is my suggestion on this issue. This does not help when they do not read it though XD.
Also specify that this tutorial doesn't include how to raise an issue because (insert reason here) maybe helpful (I'm also curious).

Hello @rammba,

I think use Contributing.md to explain Git terms is a bit weird, maybe this should be explained in the additional-material.md? On the topic of explain Git terms and give better overview to first-time users how to properly use repository and git, maybe improving the Additional material section in README.md is another approach to this problem, with something like this (rough idea):

Checkout Additional material. In there you'll find out what does merge do, what is conflict, ... etc. Also find how to properly use repository and git.

Answer 3 · 2025-11-04T16:00:02.000Z

Hey @Sharl0tteIsTaken,

I think use Contributing.md to explain Git terms is a bit weird, maybe this should be explained in the additional-material.md?

I totally agree with you. We should provide a better overview of most common terms in the additional-material.md.

I don't have an expectation of what is supposed to be on Contributing.md, other repos like numpy, matplotlib, scipy have guidelines on how to contribute to their repo, I think first contributions have a similar approach.

This repo is a bit specific because there is no common contributing guide because it's not developing any product. It's representing documentation on how to use git properly. @Roshanjossey is trying to create simple issues in order to give the community a way how to contribute besides adding the name in the list of contributors.

Answer 4 · 2025-11-05T23:38:40.000Z

it looks like we're mixing Contributing.md with a list of translators

The idea to put list of translators in Contributing.md was to make it easy for people to ask for reviews themselves.
This is not working. We literally have no one requesting for reviews.
One solution I can think of is to remove this list and handle this with GItHub action. For PR that has changes in translated files, we can automate requesting reviews.

I think best we can do is to use a bot to automatically tag someone if any files other than Contributors.md are modified, just like in #101727. Or is the bot not in use now?

This still works. https://github.com/firstcontributions/first-contributions/blob/main/.github/workflows/auto-pr-merge.yml#L197
Which uses condition from https://github.com/firstcontributions/first-contributions/blob/main/.github/workflows/auto-pr-merge.yml#L24

The only difference between them is the suffix, maybe it's hard to differentiate for someone at first glance? Has someone said something about this before?

Nobody has given this feedback but I do see some of them occasionally (maybe one per 300 PRs or so).

This does not help when they do not read it though XD.

This is the biggest problem but also the hardest (I should say impossible) to solve.

This repo is a bit specific because there is no common contributing guide because it's not developing any product.

Even if this is the case, as a gateway into open source for some people, I think we could do more to inform what is unfavourable behaviour and discourage it. For example, when I started seeing spam PRs in popular projects , I'm more inclined to close PRs like #106717

Answer 5 · 2025-11-06T10:08:24.000Z

Hey @rammba and @Roshanjossey,

One solution I can think of is to remove this list and handle this with GItHub action. For PR that has changes in translated files, we can automate requesting reviews.

I think this is a good idea, in this approach we do need to make a new translators specific file as @rammba mentioned above. However, it's important to note that some languages do not have dedicated reviewers, e.g. Bulgarian, Czech.

I think we could do more to inform what is unfavourable behaviour and discourage it.

I agree. We could create a file (e.g. unfavourable behaviour) to specify which behaviour is unfavourable, put a link to this file in issue template and Contributing.md, before the link of raise an issue (rough idea):

If you'd like to suggest a change in the tutorials or the workflow, please read through unfavourable behaviour and raise an issue.

This does not add unrelated content into README.md, it will only affect one trying to create an issue. Ignoring those don't intend to read unfavourable behaviour, I think this is one of the best approaches we got. What do you think?

Answer 6 · 2025-11-06T16:58:06.000Z

Hello @Roshanjossey, @Sharl0tteIsTaken

This still works. https://github.com/firstcontributions/first-contributions/blob/main/.github/workflows/auto-pr-merge.yml#L197
Which uses condition from https://github.com/firstcontributions/first-contributions/blob/main/.github/workflows/auto-pr-merge.yml#L24

Looks like the condition wasn't met in my PR #105548

I think we could do more to inform what is unfavourable behaviour and discourage it.

We should add a bit better explanation, but spam PRs cannot be prevented. I guess people here wants to learn how to contribute, even with spam PR.

However, it's important to note that some languages do not have dedicated reviewers, e.g. Bulgarian, Czech.

I think we should have translator list even if nobody actually assigns an issue or PR for them to review. For example, I would like to review any changes in Serbian translations. Probably there are other people who wants the same.

We could create a file (e.g. unfavourable behaviour) to specify which behaviour is unfavourable.

Maybe just a small checklist with good and bad things can do the job.

Answer 7 · 2025-11-06T17:54:13.000Z

Hey @rammba,

I think we should have translator list even if nobody actually assigns an issue or PR for them to review. For example, I would like to review any changes in Serbian translations. Probably there are other people who wants the same.

Yes, I agree that we should have a translator list. I would love to do the same for Traditional Chinese.

Maybe just a small checklist with good and bad things can do the job.

I agree with you, simple and straightforward might just to the trick.