Add strawman contributing guidelines #672
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -2,27 +2,114 @@ | |||||
|
|
||||||
| Welcome to Orcasound! We're thrilled you're interested in contributing to the site. | ||||||
|
|
||||||
| - [Code of Conduct](#code-of-conduct) | ||||||
| - [Reporting Bugs](#reporting-bugs) | ||||||
| - [Requesting New Features](#requesting-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. | ||||||
|
|
||||||
| ## 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 a 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) | ||||||
| - [Project board](https://github.com/orgs/orcasound/projects/38/views/1) | ||||||
|
|
||||||
| Once you've chosen an issue and want to contribute code: | ||||||
|
|
||||||
| 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](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. | ||||||
|
There was a problem hiding this comment. I can find existing PRs like #635 that don't follow this rule. |
||||||
| - 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 every 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) | ||||||
| - [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) | ||||||
|
Comment on lines
+101
to
+102
There was a problem hiding this comment. 🛠️ Refactor suggestion Remove outdated Trello board links. Based on previous discussions, Trello is no longer actively used. These links should be removed to avoid confusion. -- [Trello board with overview of features](https://trello.com/b/hRFh7Sc1/orcasite-development)
-- [Public roadmap](https://trello.com/b/wBg0qhss/orcasound-roadmap)📝 Committable suggestion
Suggested change
|
||||||
|
|
||||||
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. | ||||||
|
|
||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.