Clarify CONTRIBUTOR.md formatting

[francesco-ooops]

Hi, we need some guidance on how to list companies in CONTRIBUTORS.md file, as currently template only lists how to add developers but not contributing companies

I tried to check existing files but they seem to employ the most diverse formats: https://github.com/search?q=org%3AOCA%20contributors.md&type=code

could the template be updated to unify formatting? thanks!

cc @rousseldenis @ivs-cetmix

[ivs-cetmix]

I think we should use the same format for companies too. Nothing special here imho

[rousseldenis]

I think you should read this : https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

We already do that in OCA. In authors manifest section you can find companies (or individuals). In contributors, it should be individuals only.

[francesco-ooops]

Thanks for clarifying! This is what I was looking for: clear guidelines

TBH I find really counterproductive to not have a document you can point anyone to in order to support why a change is requested on a PR.

Why do we have to bicker about how to do things when we could just write it explicitly on guidelines? Then we can bicker on the guidelines if needed.

On the side: I don't think it's a good sign that guidelines have been last updated 5+ years ago. Either they are the most perfect guidelines ever, or something has been left out of the document and has just become "common practice".

I suspect it's the latter and I am asking for more experienced members to help out clarifying how something should be done instead of correcting the same issues tens of times in single PRs, delaying merge. This is not ideal at all.

---

Anyway - going back to the subject:

In authors manifest section you can find companies (or individuals). In contributors, it should be individuals only.

Sorry but this is not what the link you posted states:

Author: The person/s or organization that created the project

So now my question is: where do organizations that work on an IMP or bugfix fit?

[francesco-ooops]

cc @OCA/board
@OCA/oca-consultants (specifically on the documentation side of things)

[pedrobaeza]

We (Tecnativa) created the schema to put on CONTRIBUTORS.rst the company (with a link), and then, the list of persons, to fill the gap on that matter, and I think it's totally coherent and compatible with current guidelines and the link provided by Denis.

[rvalyi]

at Akretion we also like doing it like Tecnativa and we think it's a good balance between explicting both individuals and companies (cause companies of individuals contributors need to be shown).

BTW, we also observe some name squatting/spamming from companies multiplying noob contributions just to bloat the contributors.rst with their company name, but no system is perfect and such abuses can certainly receive enough naming and shaming so they don't try again.

[ivs-cetmix]

I think you should read this : https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

We already do that in OCA. In authors manifest section you can find companies (or individuals). In contributors, it should be individuals only.

@rousseldenis I really appreciate and share your passion for Open Source software. However I think we should be more realistic and pragmatic when it comes to the real world scenarios.
@pedrobaeza @rvalyi are offering a reasonable solution. I would suggest going further and let this to be decided by the contributors themselves. I don't see any threat to the code quality here. If there is still any I would appreciate your pointing at it.

[rousseldenis]

@rousseldenis However I think we should be more realistic and pragmatic when it comes to the real world scenarios.

I never said I disagree with them 😅. 'At least' contributor should appear. We can discuss how.

[francesco-ooops]

Please assist me in addressing the following questions:

1. Company A contracts Company B with the task "Add feature X to existing module Y" > Company B develops the code > how should both companies and developers appear in the readme file?

2. Template is not accurate as to what formatting should be used compared to what is used in actual CONTRIBUTOR files

[pedrobaeza]

Company funding developments are already covered in CREDITS.rst.

[ivs-cetmix]

Company funding developments are already covered in CREDITS.rst.

Ok, here are some use cases:

Case 1

Let' s say @pedrobaeza comes to Elop Flask and says "Hey Elop, I have a great idea of the MemERP system, give me some of your dirty money". And Elop say: "wow @pedrobaeza such much great idea! please please take my dirty money!"
In this case Elop Flask will appear in the CREDITS.md as a sponsor.
And @pedrobaeza will appear as a contributor because he has personally written this code and pushed the module to the OCA.

Case 2

Elop Flask comes to Tecnativa company and says: "I have a great idea of the MemERP system. You are such much nice Odoo developers, please please develop this, here is my dirty money".
In this case Elop not just giving his dirty money. He is also contributing his idea and functional knowledge.
But @pedrobaeza says: "thank you Elop but we can put you to the CREDITS.md only because you don't know how to write much nice python Odoo code, so we cannot credit you as a contributor. Meanwhile thank you for your idea and your dirty money".
So once again only @pedrobaeza will appear on the contributors list.

Case 3

Elop Flask comes to Tecnativa company and says: "You are such much nice Odoo developers, I would like to buy your company for a billion of my dirty money". And he buys it so now @pedrobaeza is working is the EpslaMotors company owned by Elop.
One day Elop comes to @pedrobaeza and says: "I have a great idea of the MemERP system. Please write some very nice Odoo python code for this". @pedrobaeza writes his very beautiful code and pushes it to the OCA repo.
And - surprise - still there is only @pedrobaeza who is in the contributors list.
Although he is now employed at EpslaMotors and getting his salary paid with Elop's dirty money.

Summary

We need to state clear what is considered a "contribution". There are several types of contribution:

1. Personal one. This is when someone has written code and pushed it. However there are at least functional people who design the flow, do reviews etc. Shouldn't they be credited too?
2. Resource contribution. When a company is assigning a dev to a project it means that this company is contributing its internal rehouses. Shouldn't this be credited either?
3. Financial contribution. This is when someone is just sponsoring a project. Here is more or less clear because there is a CREDITS.md already for this case.

[pedrobaeza]

For summary 1 is to put lines in CONTRIBUTORS. For summary 2, it to put current company + contributors structure in CONTRIBUTORS.

P.S.: Where's that billion dirty money?

[ivs-cetmix]

For summary 1 is to put lines in CONTRIBUTORS. For summary 2, it to put current company + contributors structure in CONTRIBUTORS.

Sounds reasonable 👍 I think we need to fix it in the module template and guidelines as soon as it's approved by the Board.

P.S.: Where's that billion dirty money?

Looks like he spent it for purchasing the Cripper social network so nothing left for the MemERP 😢

[ivs-cetmix]

@pedrobaeza we have discussed this topic with out team today and we have a question:
If someone had opened a PR and than eg @rousseldenis came to that PR, did a review and added some valuable comments that made this PR better.
Should @rousseldenis be considered a contributor and added to the "Contributors" section too?

P.S. Our question is raised by the document @rousseldenis posted above

I think you should read this : https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

[pedrobaeza]

Yes, it's a good point. Thanks for being such exhaustive.

As other things, it's subjective, as that contribution may be very minimum (just a syntactic sugar suggestion, or potential problem), or very huge (proposing a lot of things and even providing code for that proposition). It's up to both parties to agree if it should be included. If claimed by the reviewer (although normally they don't do it), or detected by the pull request author, it can be agreed and included. If there's a conflict (for example, a reviewer claims that it should be included in contributors, and the author of the PR don't consider that), a PSC can intervene to have the final word. Anyway, a reasonable argument for not including reviewers is that they already have auto-stats from GitHub, and we can encourage board for publishing this data (2022 data were published by an individual, @etobella - https://www.dixmit.com/blog/nuestro-blog-1/ranking-de-colaboradores-en-la-oca-2022-8).

[rvalyi]

@pedrobaeza we have discussed this topic with out team today and we have a question: If someone had opened a PR and than eg @rousseldenis came to that PR, did a review and added some valuable comments that made this PR better. Should @rousseldenis be considered a contributor and added to the "Contributors" section too?

P.S. Our question is raised by the document @rousseldenis posted above

I think you should read this : https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

I personally think module authors and maintainers should decide what is a contribution worth mentioning or not. If you add 20 lines of tests in some 50 lines glue module, it is certainly a OK being mentioned as a contributor. Now if you add 20 lines of test in a 5000+ lines complex module that took 10 years to build it may not be "enough" to appear as a contributor I think.

The problem is that otherwise one would appear the same as somebody who may be made 10x more work and it will ruin the idea of promoting people doing the hard work. If you start doing that you will even see companies making lot's of useless PRs just in the hope to get their name mentioned among the people who did the hard work for years and years. Remember how prostitute is the Odoo appstore if you don't believe me.

[yajo]

I think it's the 2nd time I mention https://allcontributors.org/ today! Cool, I like to see that OCA is worrying a bit more about crediting work. 😊

That site promotes the idea that any contribution should be credited. It also provides a github bot that helps materializing that idea in open source projects. We might consider using it.

So, I think we should nail this question to the important subject: why should somebody appear in the contributors section? Pick your answer:

1. To say "thank you" for contributing, so we encourage contributions.
2. To rank who contributes more.

If your answer is 1, then you shouldn't care about more contributors appearing in that list, as long as they contributed something. Actually, that'd be a good thing for you. Having lots of contributors speaks for the health of a community. Probably, a new contributor that contributes something, adds himself to the list, and sees the merge, will feel thanked and motivated to contribute more.

If your answer is 2, then you promote conflicts when somebody wants to be credited and somebody judges that they shouldn't. Probably, a new contributor that contributes something, adds himself to the list, and sees somebody judging him as "not good enough to be considered a contributor", will feel motivated to flee away from OCA and never contribute again.

What takes more hours? A functional changing a line of a README? A dev changing a test? A product manager designing a new workflow? A first-time contributor doing a functional review on runboat? A dev writing a 1000 lines module? A dev writing a 1-line fix? More important: should we care?

Are we so important so as to judge others' contributions? The fact I authored buggy code gives me the rights to decide that another person that "just" fixes a bug I created doesn't deserve my credit? The fact that I happen to know how to fix that bug means that the other person, who doesn't know python but found the bug, doesn't deserve their own credit?

Remember that we're a community. OCA's value comes from attracting more members. Having a small and harsh community where each one fights for their own egos is a recipe for disaster.

Couldn't we just be more generous and welcoming in these subjects? Simple: did you contribute? You're a contributor! ❤️

[rousseldenis]

Couldn't we just be more generous and welcoming in these subjects? Simple: did you contribute? You're a contributor! ❤️

I think that's already what is happening in PR's. I've never see people refusing adding someone to CONTRIBUTORS's list even for 'just' changing version number during migration process.

@rvalyi I think you mixed contributor and author. If indeed your contribution is worth value by refactoring a whole process, you should maybe appear in authors. Personally, I'm not refraining people to be added to contributors if they fix a one-line bug.

[rafaelbn]

Hello,

At Moduon, we strongly believe in the significant role companies play in fostering open-source growth. By allowing employees to contribute, these organizations not only promote sharing and personal/professional recognition but also contribute to the collective knowledge. In our approach, we acknowledge both the company's support and the individual's contribution. We list the company name, recognizing its encouragement and facilitation, followed by the name of the person making the contribution.

We give equal importance to functional contributions as well as to development. This includes recognizing often unseen elements such as preliminary analysis, business consultancy experience, and product management skills.

This approach aligns with our belief that every aspect of contribution, whether it's development or functional consultancy, is invaluable to the open-source community.

Best regards,
Rafael Blasco (@moduon)

Ping @vdewulf @carmenbianca

[yajo]

I've never see people refusing adding someone to CONTRIBUTORS's list even for 'just' changing version number during migration process.

I've experienced that several times. IMHO it would help a lot to the health of the OCA if we had instructions written in the contribution guide.