Skip to content

Commit

Permalink
Move contributing to own file
Browse files Browse the repository at this point in the history
  • Loading branch information
hftf committed Aug 13, 2024
1 parent 1808ccb commit 6755a90
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 2 deletions.
35 changes: 35 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# How to contribute

The college quizbowl calendar is a community-updated resource. It is not intended for a single person to update it each week, year after year.

## What does an update to the calendar involve?

At its core, updating the calendar almost entirely just means adding info to [YAML](https://learnxinyminutes.com/docs/yaml/) files (structured plain text files). An example update looks basically [like this](https://github.com/quizbowl/collegecalendar/commit/34eaa5f0d).

When | Task
-|-
Before the start of a season | Add `season.yaml` and placeholder YAML files for each expected tournament slot
After a new set is announced | Add a YAML file for the new set
After a new mirror is announced | Add it to the set’s YAML file
As other information is announced | Update above files

Minor updates are easy: find the relevant YAML file inside this GitHub repository and [edit it directly](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository). GitHub takes care of filing the pull request automatically.

For major updates, it is encouraged to set up a development environment so that you can test changes locally on your computer. There is a one-time overhead of setting up Jekyll (the static site generator), Git (version control system), and GitHub (to communicate changes with the community via pull requests) if you haven’t done so before, in addition to a learning curve for each tool. Reach out for help getting started.

## Why use GitHub PRs? Doesn't that make it harder to contribute?

The college quizbowl calendar is primarily a website (that is backed by structured data stored in plain text) and not in itself merely a database of information.

While an interactive interface triggered by a big "edit this website" button is not completely out of scope, it would be a significant amount of work, a user account system, active moderation, dynamic web hosting, and maintenance.

GitHub comes free with an existing account system, solutions for moderation and collaboration (despite a learning curve), hosting and deployment, notifications, and maintenance. Git of course provides versioning, and its distributed/pull request model allows people to work independently, although does not inherently structure coordination between people. GitHub’s convenient edit button also enables minor contributions without requiring full-fledged PRs.
Anyone coding seriously these days knows that over the last 15 years, GitHub has become standard practice for open-source tech collaboration by far and the pull request flow is a key part of coding literacy.

On the other hand, many people have no idea how to contribute, are not comfortable with Git, GitHub, or setting up dependencies like Jekyll, or are not willing to learn, team up with others, or ask for help.

So there is a trade-off. Expecting that not many people are going to bother to contribute either way, it is difficult to justify the effort of a bespoke implementation of everything mentioned above.

## Contribution process guidelines

Non-trivial pull requests should be left open for at least 48 hours to allow for review. Please don’t forget to test your changes locally. Don’t blindly push upstream if you’re a contributor with commit permissions. Keep the code clean and the commit graph sane.
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,8 @@ This project is licensed under the terms of the [GNU General Public License (GPL

Contributions are certainly welcome. Anyone with a GitHub account can easily submit issues or pull requests. Feel free to participate in community review on issues and pull requests. Ask for help if you need to.

Some guidelines: Non-trivial pull requests should be left open for at least 48 hours to allow for review. Please don’t forget to test your changes locally. Don’t blindly push upstream if you’re a contributor with commit permissions. Keep the code clean and the commit graph sane.
See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.

## Spec

See [the spec](SPEC.md) for documentation on project structure and data format.

0 comments on commit 6755a90

Please sign in to comment.