From 7872b167ed6cd4338c3fe184b75057c0ffe5eabc Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 8 Oct 2024 12:22:37 -0700 Subject: [PATCH] Add strawman contributing guidelines 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 https://github.com/orcasound/orcasite/discussions/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 --- CONTRIBUTING.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 93 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99db1012..ef5e1c19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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](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. +- 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.