awesome-selfhosted-data/CONTRIBUTING.md

Contributing

Don't know where to start? Check issues labeled help wanted, fix 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

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

Other

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://nodiscc.github.io/awesome-selfhosted-html-preview/)
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