awesome-selfhosted-data/CONTRIBUTING.md

Contributing

Don't know where to start? Check issues labeled help wanted, bug and curation.

Curation

• Software with no development activity for 6-12 months may be removed from the list
• Unmaintained software without an active community and/or persistent security issues may be removed from the list
• Problems should be reported automatically:

Add software to the list

• Create a new software/software-name.yml file, based on the template in .github/ISSUE_TEMPLATES/addition.md. Please use kebab-case for file naming, for example my-awesome-software.yml.
• Remove comments and unused optional fields
• Enter a descriptive commit message (such as add My Awesome software)
• Select Create a new branch for this commit and start a pull request
• Click Propose new file
• Click Create pull request

If you are not comfortable sending a pull request, please open a new issue.

In single page mode the software will only appear under the first category in its tags list, so choose wisely.

Add a tag/category

Tags represent functional categories/features of the software, and must be added to tags/tag-name.yml (use existing tags as example). Any tag must have a minimum of 3 software projects referencing it. The Miscellaneous tag can be used for software not matching any existing category.

# project name
name: Project Management
# description of what this tag/category is about (markdown allowed)
description: '[Project management](https://en.wikipedia.org/wiki/Project_management) is the process of leading the work of a team to achieve all project goals within the given constraints.'
# (optional) list of related tags, by name
related_tags:
  - Ticketing
  - Task management & To-do lists
# (optional) external links
external_links:
  - title: awesome-sysadmin/Code Review
    url: https://github.com/awesome-foss/awesome-sysadmin#code-review
# (optional) if this is set, no software items will be allowed to reference this tag, and the page will display a block asking to visit these links instead
redirect:
  - title: awesome-sysadmin/Continuous Integration & Continuous Deployment
    url: https://github.com/awesome-foss/awesome-sysadmin#continuous-integration--continuous-deployment

Add a license

Free and Open-Source software licenses (preferably SPDX identifier, or custom licenses, must be added to licenses.yml (use existing licenses as example):

  # short license identifier
- identifier: ZPL-1.2
  # full license name
  name: Zope Public License 1.2
  # link to the full license text
  url: http://zpl.pub/page/zplv12

Add a language/platform

Languages/requirements/technologies used to run or build the software should be listed in platforms/platform-name.yml (use existing platforms as example):

# language/platform name
name: Java
# general description of the programming language or deployment platform (markdown allowed)
description: "[Java](https://en.wikipedia.org/wiki/Java_(programming_language)) is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible."

Remove software from the list

Simply delete the appropriate file under software/ and submit a Pull Request. To do this from Github's web interface:

• use the go to file feature to open the appropriate file (e.g. software/redash.yml)
• Click the ... button at the top right of the file view, click Delete file
• In the Commit changes dialog, enter Remove SOFTWARE_NAME (reason) as your commit message, additional context in the extended description field, select Create a new branch for this commit and start a pull request., and click Commit Changes

Domain name costs

You can help cover domain name registration and renewal costs by pledging a small amount on Liberapay

Other guidelines

In addition to guidelines listed in the Pull Request template, these general rules help keep the list consistent:

• Please avoid redundant terms in project descriptions, such as open-source, free, self-hosted... as their presence on awesome-selfhosted already implies this.
• Prefer shorter forms for descriptions - for example, Minimalist text adventure game would be preferred to A minimalist text adventure game or $PROJECT is a minimalist text adventure game).
• If the the project has no documentation in English, please add (documentation in $LANGUAGE) at the end of the description.
• If the project is presented as an alternative to another service or application, please mention it as (alternative to $PRODUCT1, $PRODUCT2) at the end of the description.
• If you are adding software forked from another active project, please provide/link to a clear list of differences between both.
• If the project is forked from another project, please add (fork of $PROJECT) at the end of the description.
• If the project distributes a single static binary, please add the programming language in which it is written.

Other operations

Rename a tag/category: the tag must be renamed in the appropriate tags/mytag.yml file. All references to it must be updated in tags/*.yml and software/*.yml.

Automated tasks:

$ make help
install             install build tools in a virtualenv
import              import data from original list at https://github.com/awesome-selfhosted/awesome-selfhosted
update_metadata     update metadata from project repositories/API
awesome_lint        check data against awesome-selfhosted guidelines
export_markdown     render markdown export from YAML data (https://github.com/awesome-selfhosted/awesome-selfhosted)
export_html         render HTML export from YAML data (https://awesome-selfhosted.net)
push_markdown       commit and push changes to the markdown repository
push_html           commit and push changes to the HTML site repository (amend previous commit and force-push)
url_check           check URLs for dead links or other connection problems
authors             update the AUTHORS file
clean               clean files generated by automated tasks
help                generate list of targets with descriptions