From 7872b167ed6cd4338c3fe184b75057c0ffe5eabc Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 8 Oct 2024 12:22:37 -0700 Subject: [PATCH 1/7] 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 99db10126..ef5e1c194 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. From 211afe4ac0dd3805a9e5e0b2fbb93d086bb791cb Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 5 Nov 2024 12:27:58 -0800 Subject: [PATCH 2/7] Update CONTRIBUTING.md Co-authored-by: skanderm --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef5e1c194..99831d102 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ There are multiple ways you can ask questions: ### Meetings -We meet for one hour other Wednesday via Google Meet. You can request a calendar invite or check the +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. From a2cdd3010262fc218f752e10753b4cb429d67479 Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 5 Nov 2024 12:28:54 -0800 Subject: [PATCH 3/7] Apply suggestions from code review --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99831d102..f4361ea19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,7 +44,6 @@ If you are willing to follow the conditions of this license, check out the follo 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) From 100a2bdccbca77c7d9fcaeff38dc25cf0b946969 Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 5 Nov 2024 14:17:31 -0800 Subject: [PATCH 4/7] Address coderabbit feedback Signed-off-by: Dave Thaler --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef5e1c194..7c5133b59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,8 +3,8 @@ Welcome to Orcasound! We're thrilled you're interested in contributing to the site. - [Code of Conduct](#code-of-conduct) -- [Reporting Bugs](#bugs) -- [Requesting New Features](#new-features) +- [Reporting Bugs](#reporting-bugs) +- [Requesting New Features](#requesting-new-features) - [Contributing Code](#contributing-code) - [Contacting Us](#contacting-us) - [Resources](#resources) @@ -18,7 +18,7 @@ Please read and make sure you understand our [Code of Conduct](/CODE_OF_CONDUCT. 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 +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. From 7e03fba440fee55988529d6da9240b761b933bea Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Tue, 5 Nov 2024 14:19:23 -0800 Subject: [PATCH 5/7] Apply suggestions from code review --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9830b59c7..7069722af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,9 +45,6 @@ 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) -- [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: @@ -100,6 +97,9 @@ 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) ### Maintainers From 2bf8db54d204f615b90d439487e39b61e29f9792 Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Wed, 11 Dec 2024 13:29:50 -0800 Subject: [PATCH 6/7] Update CONTRIBUTING.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7069722af..ae57770cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,8 +98,6 @@ date and time information. - [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) ### Maintainers From 0e0cddbd06e6f293db3db3bb7899b7e54d78caa3 Mon Sep 17 00:00:00 2001 From: Dave Thaler Date: Wed, 22 Jan 2025 12:48:15 -0800 Subject: [PATCH 7/7] Update CONTRIBUTING.md --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae57770cb..5fb8086e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,6 @@ 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) ### Maintainers