Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add strawman contributing guidelines #672

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
+90 −5
Open

Add strawman contributing guidelines #672

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7872b16
Add strawman contributing guidelines
dthaler Oct 8, 2024
fa1a009
Merge branch 'main' into contributing
dthaler Oct 23, 2024
211afe4
Update CONTRIBUTING.md
dthaler Nov 5, 2024
a2cdd30
Apply suggestions from code review
dthaler Nov 5, 2024
100a2bd
Address coderabbit feedback
dthaler Nov 5, 2024
7722c1a
Merge branch 'contributing' of https://github.com/dthaler/orcasite in…
dthaler Nov 5, 2024
7e03fba
Apply suggestions from code review
dthaler Nov 5, 2024
e6fa16e
Merge branch 'main' into contributing
dthaler Nov 5, 2024
2bf8db5
Update CONTRIBUTING.md
dthaler Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 93 additions & 5 deletions CONTRIBUTING.md
View file
Open in desktop
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)
dthaler marked this conversation as resolved.
Show resolved Hide resolved

## 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).
dthaler marked this conversation as resolved.
Show resolved Hide resolved
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:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find the fact that there's multiple places to look below pretty confusing as a potential contributor. How do I decide which one to look at? Are they redundant? Is one more important than the others? Do I need to look at all of them when picking?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point! The first 3 ultimately link back to the issues page. I don't think we're directly picking issues from Figma until requested by the design team, in which case we make an issue here. I don't think we're actively using Trello these days, so we can probably remove those.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with removing Trello, these changes are perfect

- ["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)
dthaler marked this conversation as resolved.
Show resolved Hide resolved
- [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)
dthaler marked this conversation as resolved.
Show resolved Hide resolved

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.
Comment on lines +69 to +70
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are great to include, very helpful posts

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](https://github.com/orcasound/orcasite/pulls) the following rules apply:
- The pull request description should describe the problem and solution, and reference the GitHub issue if one exists.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can find existing PRs like #635 that don't follow this rule.
However, I still recommend that this rule should apply.

- 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
dthaler marked this conversation as resolved.
Show resolved Hide resolved
[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)
Comment on lines +98 to +99
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would leave these out, don't want them to get indexed by crawlers (spam potential)


dthaler marked this conversation as resolved.
Show resolved Hide resolved
### 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