Skip to content

Commit

Permalink
Add strawman contributing guidelines
Browse files Browse the repository at this point in the history
The language about the license comes from what github shows at the
top of https://github.com/orcasound/orcasite/blob/main/LICENSE.
I don't like the use of this license, and Scott's discussion in
#181 proposes changing
it, which I would prefer.  However, in this PR I just document the
current state, which may dissuade some contributors from participating.
Changing the current state, if done, would be in a separate pull
request.

Signed-off-by: Dave Thaler <dthaler1968@gmail.com>
  • Loading branch information
dthaler committed Oct 8, 2024
1 parent 02d8480 commit 02691bf
Showing 1 changed file with 93 additions and 5 deletions.
98 changes: 93 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,115 @@

Welcome to Orcasound! We're thrilled you're interested in contributing to the site.

### Code of Conduct
- [Code of Conduct](#code-of-conduct)
- [Reporting Bugs](#bugs)
- [Requesting New Features](#new-features)
- [Contributing Code](#contributing-code)
- [Contacting Us](#contacting-us)
- [Resources](#resources)

## Code of Conduct

Please read and make sure you understand our [Code of Conduct](/CODE_OF_CONDUCT.md) before contributing to the project.

### General workflow
We recommend following these steps if you'd like to contribute to the repo.
## Reporting Bugs

First, **ensure the bug was not already reported** by searching on GitHub under
[Issues](https://github.com/orcasound/orcasite/issues).

If you found bug, you can help us by
[submitting a GitHub Issue](https://github.com/orcasound/orcasite/issues/new).
The best bug reports provide a detailed description of the issue and step-by-step instructions
for reliably reproducing the issue.

## Requesting New Features

You can request a new feature by [submitting a GitHub Issue](https://github.com/orcasound/orcasite/issues/new).

If you would like to implement a new feature, please first
[submit a GitHub Issue](https://github.com/orcasound/orcasite/issues/new) and
communicate your proposal so that the community can review and provide feedback. Getting
early feedback will help ensure your implementation work is accepted by the community.
This will also allow us to better coordinate our efforts and minimize duplicated effort.

## Contributing Code

Orcasite is currently covered by the [GNU Affero General Public License v3.0](https://github.com/orcasound/orcasite/blob/main/LICENSE). Permissions of this strongest copyleft license are conditioned on making available
complete source code of licensed works and modifications, which include larger works using a licensed
work, under the same license. Copyright and license notices must be preserved. Contributors provide
an express grant of patent rights.

If you are willing to follow the conditions of this license, check out the following links
to find an unassigned item to contribute to:

- ["Good first issue" GitHub issues for first-timers](https://github.com/orcasound/orcasite/labels/good%20first%20issue)
- ["Help wanted" GitHub issues](https://github.com/orcasound/orcasite/labels/help%20wanted)
- [Project board](https://github.com/orgs/orcasound/projects/38/views/1)
- [Figma](https://www.figma.com/design/41JuvNkXJhTUob8HMsJiNC/Orcasite%3A-design-updates?node-id=882-3971)
- [Trello board with overview of features](https://trello.com/b/hRFh7Sc1/orcasite-development)
- [Public roadmap](https://trello.com/b/wBg0qhss/orcasound-roadmap)

Once you've chosen an issue and want to contribute code:

0. Check out the [Trello board](https://trello.com/b/hRFh7Sc1/orcasite-development) for an overview of features being worked on.
- This [public roadmap](https://trello.com/b/wBg0qhss/orcasound-roadmap) has a higher level view.
1. Fork the Orcasite repo.
2. Develop on a [feature branch](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow).
3. Submit a PR (don't review your own)!
- To maintain a consistent style, we recommend running [Prettier](https://github.com/prettier/prettier) on js, and `mix format` before submission.
4. Once a PR is merged, we can throw it up onto the dev server to see how things look!

### Submitting a Pull Request

For all but the absolute simplest changes, first find an existing GitHub issue or
[submit a new issue](https://github.com/orcasound/orcasite/issues/new) so that the
community can review and provide feedback. Getting early feedback will help ensure your work
is accepted by the community. This will also allow us to better coordinate our efforts and
minimize duplicated effort.

If you would like to contribute, first identify the scale of what you would like to contribute.
If it is small (grammar/spelling or a bug fix) feel free to start working on a fix. If you are
submitting a feature or substantial code contribution, please discuss it with the maintainers and
ensure it follows the public roadmap. You might also read these two blogs posts on contributing
code: [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) by Miguel de Icaza and
[Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) by Ilya Grigorik.
All code submissions will be reviewed and tested, and only those that meet
the bar for both quality and design/roadmap appropriateness will be merged into the source.

For all pull requests the following rules apply:
- The pull request description should describe the problem and solution, and reference the GitHub issue if one exists.
- Existing tests should continue to pass.
- Tests should ideally be included for every bug or feature that is completed.
- Documentation should be included for every feature that is end-user visible.
- Coding style should be consistent with the style used in other files of the same type in this repository.

## Contacting Us

### Questions?

We are happy to answer as best we can any question you have about Orcasite.
There are multiple ways you can ask questions:

- Using the [Zulip channel](https://orcasound.zulipchat.com/#narrow/stream/437031-orcasite)
- Using [Github discussions](https://github.com/orcasound/orcasite/discussions)

### Meetings

We meet for one hour other Wednesday via Google Meet. You can request a calendar invite or check the
[Zulip channel](https://orcasound.zulipchat.com/#narrow/stream/437031-orcasite) for the latest meeting
date and time information.

- [Request a calendar invite](https://forms.gle/Tegj4x6qxWx7PSes5)
- [Meeting link](https://meet.google.com/igp-gpdr-wwu)
- [Meeting notes](https://docs.google.com/document/d/1zXngvGO5kdm24gqSTNfHleFifU6ldtbA4amGSXe5jpg/edit?tab=t.0#heading=h.qyef7i4h6hom)

### Maintainers

If you have any questions about parts of the architecture and site, these are contributors with context about various parts:

- [Paul Cretu](https://github.com/paulcretu) - Orcanode, streaming backend, ffmpeg
- [Skander Mzali](https://github.com/skanderm) - Elixir backend, JS/React frontend

## Resources

### Learning resources
If you're new to Elixir (or JS and React), that's no problem! Here are some resources for learning what they're about.

Expand Down

0 comments on commit 02691bf

Please sign in to comment.