Godot-docs: How to give credit where it's due

[akien-mga]

We're starting to have a nice pool of contributors to the documentation, both little hands doing all the maintenance and proofreading necessary on most pages as well as people focusing on a specific area and writing lengthy tutorials.

So far we haven't given contributors much credit apart from the "and the Godot community" in the copyright statement, so there's room for improvement.

How should we do it?

An obvious first step would be to add an AUTHORS.md file to the repo with a list of contributors, as we have on the code repo.

In the code repo I'm listing only contributors with over 10 commits, which is quite arbitrary, but allows to keep a reasonably well curated list of people who had some kind of role in developing Godot (excluding people who did one commit to fix a typo in the README for example). For the docs repo, such a lower limit might be too strong, as we have people who wrote thousands of words of documentation in one or two commits and would not make it to the AUTHORS file with this rule.
With the 10 commits rule we'd have only 14 authors, versus 252 with a 1 commit rule (see https://github.com/godotengine/godot-docs/graphs/contributors). With a 3 commits rule we'd be at 58.

Next to this, do we want a system to show when a given contributor wrote a whole page? On the one hand it's nice for someone who spent many hours working on a tutorial to be credited for it explicitly, on the other hand every single page was written by a contributor at some point, and after years of rewriting and improvement by other contributors, this "initial author" information would lose of its relevance. Suggestions welcome :)

[OvermindDL1]

To initially generate the file could simply go over the commits and check the changecount, if it exceeds something like 10 lines of changes or so then add them? Simple couple-line script to do that initial generation (or bake it in an run it on occasion to update the file automatically, perhaps with stats as well).

[cbscribe]

In the case of some tutorials, pointing to an author can be beneficial, as that's the person who knows the material the best. It's definitely nice when there's a "point person" for a certain specific document, such as the FPS tutorial. As you said, the problem with this is that the material changes over time, but I think the "initial author" is still valid, at least until the doc is completely rewritten.

[BastiaanOlij]

Indeed, a challenging predicament. People will come and go so I agree the initial author will loose its value after time. I'm also not sure how justifiable it is anyway, I just wrote up the tutorials for GDNative, but they are based off of Karroffels work and what he started with in some of the updates on the blog. I'm just the one who found time to actually work it into a tutorial. Is it right for my name to be highlighted here? The recognition is nice but...

I think Overmind's idea has the most merit, decide on who to include in the authors list based on the volume of changes. Anyone who adds more then a few paragraphs of documentation makes it onto the list with our eternal gratitude.

[Calinou]

Should there be a page listing all contributors or just a Markdown file in this repository?

[akien-mga]

I think a Markdown file is a good start. We can always do more later on but we first have to define the criteria to be in the file.

Judging by the volume of changes is a good criterion, but it requires some work to actually figure it out. Someone who have to write a script that parses all commits to count how many LOCs were added by a given contributor. This might exist already though.

Otherwise, my good ol' "10 commits and you're in" that i use for the main engine repo works fairly well. After doing some remapping for people using different names/emails, I get:

   370  Rémi Verschelde 
   151  Hugo Locurcio 
   123  corrigentia 
    94  Max Hilbrunner 
    91  Juan Linietsky 
    90  skyace65 
    84  Michael Alexsander 
    65  Andrew Conrad 
    63  Chris Bradfield 
    63  Nathan Lovato 
    47  clayjohn 
    35  Julian Murgia 
    30  Yuri Roubinsky 
    22  Poommetee Ketson 
    19  Kelly Thomas 
    18  Aaron Franke 
    18  bitbutter 
    17  Griatch 
    17  Leon Krause 
    16  Yuri Sizov 
    16  skyace65 
    14  George Marques 
    14  ZX-WT 
    13  Andrii Doroshenko 
    13  FeralBytes 
    12  Frido 
    11  Paul Joannon 
    11  puchik 
    10  Ignacio Etcheverry 
    10  Will Nations

(I would list authors alphabetically and not by number of commits eventually.)

Some prominent contributors who contributed big pieces but less than 10 commits are however missing.

[mhilbrunner]

Either we add those contributors manually as a one-time thing now when first creating the list, or we keep it simple. I wouldn't overcomplicate it :)