[MUST] Credits are missing

[jason-fox]

According to the contribution requirements, credit must be given to developers who contribute to the development of each component. A simple way to do this is to add and maintain a CREDITS file.

The list of previous contributors can be obtained using the following command:

git shortlog -cse

• MUST Requirement from the TSC

[dcalvoalonso]

Regading this issue: do you think that it is really needed to have this CREDITS file?

I mean, the list of contributors for the repository can be easily checked in https://github.com/telefonicaid/iotagent-node-lib/graphs/contributors and it is automatically generated and maintained without the need for manual/human intervention.

How this is done in other big open-source projects? I have done a quick search:

• Kong: No credits file.
• Kubernetes: They have some files to manage owners, owners' aliases... But there is not a file to recognize contributors.
• Ansible: No credits file.
• Tensorflow: Code owners file, but no credits one...

[fgalan]

I agree with @dcalvoalonso that (as any other piece of static information in the repository ;) a CREDIT file could get obsolete easily.

What about one-line CREDIT file with a link to the URL of the contributor graph in github? (Just thinking aloud...)

[dcalvoalonso]

What about one-line CREDIT file with a link to the URL of the contributor graph in github? (Just thinking aloud...)

+1

[jason-fox]

The only problem with that approach is that it isn't really trying to give credit. If you want someone to work for free and you want to acknowledge them you make the effort to do so, otherwise why bother.

All this comes down to is a maintenance overhead issue. You don't necessarily want to have to regenerate or amend the list every time.

How about generating the the current list for all names who have contributed up to now and add a disclaimer at the bottom.

e.g.

Many thanks to all our contributors how have helped make this project a success, they are listed below in order of commits

• XXXX
• YYYY
• ZZZZ
• etc...

This list is periodically updated, a complete up to date list can be found here

With the link at the bottom. The list itself could be regenerated infrequently - say once a release or once a year at the same time as the copyright statements

[fgalan]

The only problem with that approach is that it isn't really trying to give credit. If you want someone to work for free and you want to acknowledge them you make the effort to do so, otherwise why bother.

I'm afriad I'm not getting your point. Why the linked contribution graph would not give credit? I mean, if I go to https://github.com/telefonicaid/iotagent-node-lib/graphs/contributors right now I see:

where dmoranj, dcalvoalonso, AlvaroVega, fgalan, json-fox, chicco785 and many others (not shown in the snapshot due to scroll) are getting proper credit.

Maybe I'm missing something... :)

[dcalvoalonso]

I fully agree with @fgalan. I see my contributions very well recognized with the information of https://github.com/telefonicaid/iotagent-node-lib/graphs/contributors.

[jason-fox]

If you take GitHub's most contributed project torvalds/linux , you will also see a CREDITS file

• https://github.com/torvalds/linux/blob/master/CREDITS

Even when you scroll, the equivalent contributors function on GitHub, is limited to the first 100 contributors only

• https://github.com/torvalds/linux/graphs/contributors

The GNU public license recommends (?) listing by author -

• Random example

If the requirement is to offer credit to contributors it should be done properly or not at all.

Also something like this may be relevant (IANAL) - there may be advantages to adoption if authors are properly credited if code is to be used or expanded elsewhere.

[jason-fox]

The relevant section of the contributor guidelines references nodejs as an example (and predates my involvement in the project as it was also present in the source forge media wiki)

Credits MUST be given to external contributors. A CREDITS file MUST be present at the root directory of the GE code repository, including one line per contributor to the project. An example can be found here.

[dcalvoalonso]

To be honest, I don't like the approach at all. Anyway, as @fgalan and @AlvaroVega are the owners of the repository, the decision is up to them. :)

[jason-fox]

@dcalvoalonso - I don't write the rules, I just try to enforce them. 👮

The rules were discussed at length by the TSC, amendments to the contributions were requested by PR and discussed and accepted and the roadmap meeting further discussed all MUST requirements and downgraded some as unworkable. Credits was left in the MUST list.

[fgalan]

IMHO, both approaches (file with author names vs. file with a link to the github contributors graph) provide proper credit (i.e. both list the authors based in their contribution degree). So, in that sense they are equal and the decission between one versus other should be done based in other aspects.

From a point of view of maintenace and obsolescence, github contributors graph clearly advantages to file with author names. Note that to create and mantain the latter one, it isn't just a matter of executing git shortlog -nse and capturing the output into a file. Next you have to clean up the results, which can be costly in long lived repositories. For instance, take into account git shortlog -nse output at Orion repository. You cannot use that file directly, you have to manually aggregate entries corresponding to the same person and reorder. And you have to do this each time you want to update the file. On the other side, github contribution graph has zero cost and it's always updated.

The only aspect in which file with author names may advantage to github contributors graph is the case in which you take your code out of github to continue the development in another place. However:

• Is that a realistic posibilty in our case? Specially when FIWARE rules mandate to use github
• Even if that rare case may happen some time in the future, you can (in that moment and not before) edit the CREDIT file and replace the link by an actual list of names.

Regarding projects you cite, although of course the Linux kernel is one of the most relevant projects in the open source ecosystem, not sure if it is a good reference in this case. It is a project started much before github was used to keep the code so for them contributions graph possibility didn't exist when they started.

Regarding "rules & regulations" :), I think this time FIWARE rule wording is too strict. I mean, I agree it's a good idea to have authors properly credited and that a rule stating that is ok. However, the rule shouldn't go beyond that point and the specific detail on how that should be done should be flexible. If some team wants to use a lists with authors, fine with that. If some other team wants to use a link to contributors grpah (as this repository, in which both Atos and us prefer so) fine also with it.

TSC rules are not written in stone :) and when new information and discussion arises (was the possibility of using github contributors graph evaluated when the credits rule was decided?) it is ok to ammend them. In fact, we are doing this in a regular basic and have recent examples of it, as the amendment for docker requirements, the amendment about roadmap or the amendment about anchor usage in links for non-English languages.

[jason-fox]

@fgalan - to misquote John Maynard Keynes:

When facts change, I change my opinions. What do you do sir?

Feel free to raise a PR explaining why you think the rule should be relaxed, get the PR discussed and accepted and this issue can be completed to your satisfaction.

There is small difference between this case and the other PRs you cite, in that Docker and Roadmap were discussed in open TSC before an agreed text was added. The CKJ amendment is a relaxation of a rule I drafted (to overcome a ReadTheDocs rendering issue) and therefore I fully understand the implication of amending the rule (to the better I might add)

The statement about CREDITS has lain unaltered in the Contribution requirements for ~5 years and wasn't drafted by me in the first place. I wouldn't like to alter it unilaterally without getting some further input as to why it was drafted that way in the first place. Most other GEs have simply run the script as requested.

If it is wrong I guess no-one realized that the requirement would be too burdensome, if it was drafted that way with purpose I guess it has been done as an effort to attract a larger development community.

Or maybe someone though Node.js does it this way so it must be good. :smile:

[jason-fox]

The Github Open Source Guide recommends adding a CREDITS - see here. They recommend the format used in Sinatra - but only as an example

[jmcanterafonseca]

I think the CREDITS file has the advantage of being more semantic, in the sense that you can understand very easily what was provided by each contributor. on the other hands it has the burden of having to keep it updated, but that could be done per significant PR.

just my two cents. In any case if someone thinks that contribution guidelines should be changed a PR or similar shall be raised.

Thanks!

[fgalan]

@jason-fox don't get me wrong :) I'm not proposing to change the rule unilaterally. Creating a PR on the contribution guidelines repository and open discussion there is definitively the best way to proceed. I'll do that.

[fgalan]

PR created at https://github.com/Fiware/contribution-requirements/pull/39

[fgalan]

@jason-fox I understand this PR #766 solves the issue, so I'm closing it. Please reopen it and comment what's pending/missing if I'm wrong.