Skip to content

Express gratitude to your contributors.

License

Notifications You must be signed in to change notification settings

kudos-txt/kudos.txt

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Github (tag) Github (license) Github (issues) Github (pull requests)

kudos.txt

Express gratitude to your contributors.

Motivation

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.

Description

Kudos (from the Ancient Greek: κῦδος) is acclaim or praise for exceptional achievement.

What is kudos.txt

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.

Why a text file

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.

Differences to humans.txt

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.

Requirements

A Text Editor is helpful.

Installation

No installation is needed. Just download the kudos.txt.

Usage

Copy the kudos.txt to your repository and fill in your data.

Syntax

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>

Section

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.

  1. project

    This section consists of information about the project.

  2. contributor

    A section containing a list of your contributors with some optional information.

  3. partner

    A section containing a list of your partners, if you have some and want to mention them.

  4. software

    A section containing a list of used software or libraries in your project.

Item

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:

  1. name

    The real name, nick or any other presentation of "who".

  2. site

    A website url like "https://example.com". You can specify multiple urls separated by commas.

  3. blog

    A blog url like "https://blog.example.com".

  4. 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".

  5. news

    A support url to your newsfeed or newsletter or any other source of news.

  6. mail

    A mail address to contact the name like "[email protected]"

  7. 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.

  8. home

    An indicator of your home. You can use as many information as you want separated by commas.

  9. work

    An indicator to show your workplace. This can be the company name or job title or job description or something abstract.

  10. note

    A field, where you can put any other note down.

Example

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.

FAQ

  1. Q Do I need to put information 'xxx' in my kudos.txt?

    A No, you can reduce the amount of information, if you want.

  2. Q Why are 4-letter / 4-character items enforced?

    A This allows a very clear readability for many humans.

  3. 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.

  4. 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.

  5. 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.

Contribute

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.

License

This work is licensed under a BSD-3-Clause License.

Contact