14

In trying to deal with a codebase that was originally proprietary and then open sourced, new contributors are coming along. Each file has names on it (though usually the main author's).

At this point, the codebase is drifting considerably. Maintaining a list of names in each file seems to clutter it, and introduces an unnecessary awkwardness of "when a change is significant enough to be on the list". There's also an issue of accuracy, because the name is generally not the person to try and contact about issues.

I was thinking that it would be best to just strike the names entirely, rely on the git blame log, and switch to a CONTRIBUTORS file. (This is along with a general push to take stuff repeated in each file and move it out to coding guidelines documents, etc.)

This project is on GitHub and is:

  • mostly C code
  • has a README.md as its entry point for describing the project (80-column limited)
  • has a LICENSE in text file format (Apache2)

So what sort of model might one use for a contributors file? An all-caps CONTRIBUTORS seems like a long name. Wondering what people call it and what would go in it.

It hit me right after asking that CREDITS.md would be a good short name (somewhat obvious, and I've even used it in the past I believe). But I wasn't acknowledging individual contributors to the code when I did this before, I was acknowledging the sources drawn from (libraries, tools, etc.) to build it.

So it still strikes me that these might be different files. But maybe they could both go in one? Then CONTRIBUTORS would be a section heading in the CREDITS.md file.

Improve this question
6
  • I personally dislike text THAT YELLS AT ME. I also personally think that this issue is so small compared to anything else, that it doesn't matter much. YMMV.
    – Martijn
    Aug 12, 2015 at 10:29
  • 1
    @Martijn If a question doesn't matter, why would one comment on it?
    – HostileFork says dont trust SE
    Aug 12, 2015 at 11:08
  • because you're asking it regardless, so either you've considered whether it's worth going further in to, and decided it is, or haven't given it any consideration. If it's the second, the comment would let you think about it. If it's the first, you can freely ignore it, it's only a comment.
    – Martijn
    Aug 12, 2015 at 11:10
  • 1
    @HostileFork Since you're using the Apache 2 license, have you considered making a NOTICE file with the information in it? A list of contributors may be a good fit for that.
    – Zizouz212
    Aug 12, 2015 at 11:45
  • Maybe "awkward" but necessary to record whose contribution is copyright by the contributor and whose is not.
    – Glenn Randers-Pehrson
    Aug 12, 2015 at 12:55

4 Answers 4

Reset to default
7

Since you are using .md file, I take it that people won't be looking at the raw stuff with all the stars and what not. People will look mostly at the way that the file is "marked down". This means that you can use headers, and emphasis just like you note.

There isn't really a "standard" of doing this: Most projects create their own policies and standards to deal with varying situations in all aspects of project management, including contributions.

If you do create a Credits.md file, it would make perfect sense to include your contributors, as well as your sources. The markdown format will allow easier readability, and hence organizations between sources and contributors.

Separate files don't tend to be an issue either: If you feel that one file becomes too large and thus virtually overshadows other critical sections of files, then it becomes easier also to split them up.

If you have an avid list of contributors, and you are recording each contribution they make to various files, then it would make perfect sense to keep them in separate files, just like I mentioned above.

Improve this answer
1
7

There is no standard way of listing contributors, but there are some conventions and habits.

The GCC compiler has a MAINTAINERS file (in its source tarball) which could inspire you

Improve this answer
1
  • 1
    AUTHORS is another one I think I remember seeing, somewhere. I think I might go with CREDITS, and put the people most involved up top and then go on to the libraries, because the people contributing directly are likely to be more miffed if not at the top of the file. :-/
    – HostileFork says dont trust SE
    Aug 12, 2015 at 18:01
5

Apparently theres this standard/specification/bot:

https://allcontributors.org/

Here is more info:

https://allcontributors.org/docs/en/overview

And here is a big example:

https://github.com/all-contributors/all-contributors#contributors-

Improve this answer
1
  • That's a handy proposal, especially for large projects, but I don't think it's widely adopted enough that it qualifies as a standard.
    – David Z
    Dec 31, 2021 at 2:46
1

Humans.txt is a good candidate. It was made for websites but it could be used anywhere since it’s basically a list of contacts. https://humanstxt.org/

Improve this answer
3
  • 1
    At the moment, I think that suffers from the same problem that David Z identifies with allcontributors,org, above: it is by no means sufficiently widely adopted to constitute a standard.
    – MadHatter ♦
    Nov 4, 2022 at 10:08
  • True. The conclusion might be that there is no widely agreed upon format, so we just have to start somewhere and push one of these (and certainly not create a new format) insert xkcd standards here lol
    – redben
    Nov 9, 2022 at 6:11
  • Or alternatively, accept that there's no widely-accepted standard, stop looking for one, and just do something reasonably sensible. I think that's basically Zizouz212's accepted answer, above.
    – MadHatter ♦
    Nov 9, 2022 at 6:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.