10

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.

  • 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 '15 at 10:29
  • 1
    @Martijn If a question doesn't matter, why would one comment on it? – HostileFork Aug 12 '15 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 '15 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 '15 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 '15 at 12:55
6

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.

  • Well, it's not the Debian credits list, so I guess one file will do! CREDITS.md, start with the individual contributors in one section, then libraries and tools used below. – HostileFork Aug 13 '15 at 10:52
6

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

The GCC compiler has a MAINTAINERS file which could inspire you

  • 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 Aug 12 '15 at 18:01

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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