Skip to content

Latest commit

 

History

History
118 lines (81 loc) · 6.7 KB

CONTRIBUTING.md

File metadata and controls

118 lines (81 loc) · 6.7 KB
Raw

Contributing

Hi there! We're excited you have ideas to improve topics and collections. You're helping the community discover valuable information.

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

There are a few ways you can contribute:

  • Improving an existing topic or collection
  • Curating a new topic or collection

As you write content, check out the Style Guide to learn what each field means, and how it should be formatted. Following the style guide will increase the chances of your contribution being accepted.

Notes:

  • Updates won't immediately appear once we've merged your PR. We pull in these changes regularly to GitHub.
  • Please limit your pull request to the creation/updating of one topic or collection at a time.

Improving an existing topic or collection

If a topic or collection already exists, it will be listed in its respective directory:

The topic or collection name should match its URL, e.g. https://github.com/topics/rails corresponds to the topics/rails directory.

To make an improvement, please open a pull request with your proposed changes.

Update the image

To update the image, simply replace the image inside the directory for the topic or collection.

Update text and links

To update text and links, edit the index.md inside the topic or collection's directory. These files are formatted using a combination of Front Matter and simple body content.

For topics, you'll notice that, in examples like the topic "algorithm," data like its canonical URL, Wikipedia URL, or display name are called out in key-value pairs, while its detailed description is accounted for in the body of the document.

/topics/algorithm/index.md:

---
aliases: algorithms
display_name: Algorithm
short_description: Algorithms are self-contained sequences that carry out a variety of tasks.
topic: algorithm
wikipedia_url: https://en.wikipedia.org/wiki/Algorithm
---
Algorithms are detailed sets of guidelines created for a computer program to complete tasks efficiently and thoroughly.

Similarly, collections like "music" call out things like their author and display name in Front Matter variables -- with a detailed description in the body of the document. Most importantly, though, collections identify their individual collection items in a YAML list for the key "items."

/collections/music/index.md:

---
items:
 - beetbox/beets
 - scottschiller/SoundManager2
 - CreateJS/SoundJS
 - musescore/MuseScore
 - tomahawk-player/tomahawk
 - cashmusic/platform
 - mopidy/mopidy
 - AudioKit/AudioKit
 - Soundnode/soundnode-app
 - gillesdemey/Cumulus
 - metabrainz/picard
 - overtone/overtone
 - samaaron/sonic-pi
display_name: Music
created_by: jonrohan
---
Drop the code bass with these musically themed repositories.

The pull request template also provides guidance on the information you need to include.

Please fill out the pull request template completely, if you do not fill out the template, your PR will be closed.

Curating a new topic or collection

If a topic or collection is not yet curated, it will NOT be listed in its respective directory.

We are likely to consider suggestions to curate a topic or collection that is valuable to GitHub's community. Valuable topics, for example, include those that are already widely used by repositories and could benefit from the addition of important information. When suggesting content, please consider how to make your contribution broadly useful and relevant to others, rather than serving a specific use case.

Please note that all suggestions must adhere to GitHub's Community Guidelines and Terms of Service. Per our Terms of Service, you are responsible for the content you contribute, and you must have the rights to use it.

To propose a new topic or collection, please open a pull request with your proposed additions. The API docs and style guide provide guidance on the information you need to include and how it should be formatted.

This repository includes a list of the most-used GitHub topics that don't yet have extra context. If your pull request adds one of these topics, please update topics-todo.md so that the topic is checked (marked complete).

Please fill out the pull request template completely. If you do not fill out the template, your pull request will be closed.

Guidelines

  • Avoid conflicts of interest. These should be of general community interest, not a marketing vehicle for a product or a personal project. If you are a direct employee of a company creating the project, or the creator and sole maintainer, it's unlikely to be accepted.
  • We love experimenting with new technologies, and we are especially fond of GitHub Copilot. But as with all new technology, many of us are still getting accustomed to using generative AI tools effectively. Here are important guidelines to follow when using generative AI to contribute to this repository (adapted from the GitHub Community Discussions CoC):
    • Read and revise the content before you post it. Use your own authentic voice and edit.
    • Do not post AI-generated content verbatim to pad out the size and number of your contributions. Your changes should materially improve the site, not just say the same thing in different words.
    • AI tools will often provide completely inaccurate or invented answers to prompts. Verify with an independent source that the information is correct before including it.

Running tests

There are some lint tests in place to ensure each topic is formatted in the way we expect. GitHub Actions will run the tests automatically. If you want to run the tests yourself locally, you will need Ruby and Bundler installed.

You can run the tests using:

bundle install
bundle exec rubocop