Express gratitude to your contributors.
Thousands of Open Source Repositories are hosting code. But we should never forget, that this code is made by people. Are these people getting the gratitude they deserve? We think, it is time to have a kudos.txt to express the gratitude to all of the contributors and give them a place outside of git logs.
Kudos (from the Ancient Greek: κῦδος) is acclaim or praise for exceptional achievement.
kudos.txt provides a format to express gratitude to your contributors. It is easy to understand, easy to read for humans and machines and it does not force you to present data, that you don't want to present. You can extend it or reduce it to your needs.
A text file is easy to read from humans and machines. It is portable and can be used in any OS. It does not require a graphical desktop and can be read and manipulated even without a text editor.
humans.txt is a very nice approach. In fact, it even inspired the creators of kudos.txt. Nevertheless, the approach is different.
- humans.txt focusses on websites, kudos.txt can be used for any contribution.
- humans.txt is not easy to be read from machines / software, kudos.txt uses yaml syntax.
- humans.txt uses indicators of different length, kudos enforces 4-character indicators.
- humans.txt differentiates between team and outside collaborators, kudos.txt does not. Everybody should be seen as a contributor, when interacting with a project.
A Text Editor is helpful.
No installation is needed. Just download the kudos.txt.
Copy the kudos.txt to your repository and fill in your data.
Kudos.txt is heavily inspired by YAML. You will find the following parts in the example kudos.txt:
# The (<...>) are indicating, that you should replace them with your string.
# A leading hash (#) indicates a comment.
# <comment>
# A section has no indention.
<section>:
# Each section contains of list items (-), which can have multiple items and
# values assigned.
- <item1>: <value1>
<item2>: <value2>
- <item3>: <value3>
<item4>: <value4>
Definition: a word, which indicates a context
The <section>: is indicating a context switch. For now, the below sections are
defined and standardized. You can add more, if you feel the need. Please also
feel free to open an issue.
-
project
This section consists of information about the project.
-
contributor
A section containing a list of your contributors with some optional information.
-
partner
A section containing a list of your partners, if you have some and want to mention them.
-
software
A section containing a list of used software or libraries in your project.
Definition: a 4-letter word, which indicates a specific type of information
Items are indicators for a specific information. You can use them optionally in any section. The example kudos.txt is giving an idea, what makes sense. You can add new items, if you feel the need. The standardized items are:
-
name
The real name, nick or any other presentation of "who".
-
site
A website url like "https://example.com". You can specify multiple urls separated by commas.
-
blog
A blog url like "https://blog.example.com".
-
help
A support url like "https://help.example.com" or a support contact like "[email protected]" or a support contact number like "+49 111 222 333".
-
news
A support url to your newsfeed or newsletter or any other source of news.
-
mail
A mail address to contact the name like "[email protected]"
-
chat
A chat address in the form of "skype:mynick" to present your nick or "slack:mychannel" to indicate a channel or "https://chat.example.com" to indicate a url to your chat information.
-
home
An indicator of your home. You can use as many information as you want separated by commas.
-
work
An indicator to show your workplace. This can be the company name or job title or job description or something abstract.
-
note
A field, where you can put any other note down.
Names derived from Alice and Bob
Simple Example
If you want to list the contributors, this example may be a good start.
project:
- name: Alice and Bob - The Movie
site: https://example.com
contributor:
- name: Alice
role: Main Character
- name: Bob
- name: Carol
- name: Chuck
role: Bad guy
Advanced Example
You can also put empty lines between each item, for better readability and provide addional information
project:
- name: Alice and Bob - The Movie
site: https://example.com
mail: [email protected]
contributor:
- name: Alice
role: Main Character
mail: [email protected]
home: Not in wonderland
- name: Bob
role: Main Character
mail: [email protected]
note: Bob sends many mails.
- name: Chuck
role: Bad Guy
mail: [email protected]
work: room 404
partner:
- name: example.org
site: https://example.org
note: Very useful for examples.
software:
- name: VIM
note: Any other editor may work, too.
-
Q Do I need to put information 'xxx' in my kudos.txt?
A No, you can reduce the amount of information, if you want.
-
Q Why are 4-letter / 4-character items enforced?
A This allows a very clear readability for many humans.
-
Q I want to have a section "developers" and "managers". Is this possible?
A Yes, you can add sections, if you want. Please also feel free to contribute.
-
Q Do you offer any tools to parse the kudos.txt in [html|markdown|json|x]?
A Not yet, but this is definitively the plan. Please feel free to help.
-
Q Why do you came up tith kudos.txt?
A We wanted to establish something standardized, machine and human readable to express gratitude to contributors, partners, etc.
Thank you so much for considering to contribute. We are very happy, when somebody is joining the hard work. Please fell free to open Bugs, Feature Requests or Pull Requests after reading the Contribution Guideline.
See who has contributed already in the kudos.txt.
This work is licensed under a BSD-3-Clause License.
- Site https://kudos-txt.io
- Twitter https://twitter.com/wtd_news
- Code https://github.com/kudos-txt
- Mail [email protected]
- IRC freenode, #while-true-do
- Telegram https://t.me/while_true_do