From f7e6b53d23ef4769483a6350f8d1bd93628d3d2f Mon Sep 17 00:00:00 2001 From: Colin Clark Date: Fri, 14 Oct 2022 14:27:58 -0400 Subject: [PATCH 1/3] Resolves gh-54: Adds a contributor's guide document. Also adds a note to the README about reciprocity in open source. --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 +++++++ 2 files changed, 72 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..da6fc41 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to `Signaletic` + +Thanks for contributing to this project. Please read through this page to help you understand what to expect from the process. + +## Code of Conduct + +This project is governed by the [Signaletic Code of Conduct](CODE_OF_CONDUCT.md). All contributors are expected to respect these social practices. + +## Process/Workflow + +To contribute a bug report or feature request: + +1. Search [our issues](https://github.com/continuing-creativity/signaletic/issues) to confirm that the issue hasn't already been reported. +2. Create a new bug report, following the guidance in the issue template. +3. Discuss the bug report in the ticket and in community forums. + +If you would like to contribute a code or documentation change to address an issue or add new features or functionality: + +1. First file an issue in the [project's issue tracker](https://github.com/continuing-creativity/signaletic/issues) as outlined above. This should describe the nature of work, what's involved in implementing it, and any questions or challenges that you're aware of in the task. +2. Fork the project repository. +3. Create a branch based on the latest code in the `main` branch. +4. Make the changes described in the associated ticket (see "Coding Guidelines" below). +5. Submit a pull request against the project repository's `main` branch. If the pull request is meant to resolve a known issue, include text like "Resolves #18", "Fixes #28" in the pull request title and in appropriate commit messages. +6. Work with reviewers to discuss your changes and address any feedback. + +### Coding Guidelines + +In general, pull requests should: + +1. Provide meaningful commit messages (see below). +2. Include tests verifying the changes (see below). +4. Update or add markdown documentation for API changes. +5. Provide documentation for new functions. + +#### Commit Messages + +All commit log messages should include the following information: + +1. A reference to the GitHub issue this commit applies to (at the beginning of the first line). +2. A meaningful, but short description of the change. + +A good commit message might look like: + +```shell +commit -am "gh-12: Initial implementation of neutron flow reversal." +commit -am "gh-12: Adds documentation based on PR feedback." +``` + +#### Tests +The tests for this package are currently written using +[Unity](http://www.throwtheswitch.org/unity), and can be run for both native and Web Assembly builds. See the [project README](README.md) for more details. + +#### Lint Your Code + +Signaletic does not yet include any automated lint checks. In the meantime, here are some basic stylistic guidelines: + +1. Use four spaces for indentation +2. Avoid platform-varying types (such as ```short``` or ```long```) in favour of the C99 fixed-width types (e.g. ```int16_t``` and ```int32_t```) +3. Pointers should be defined as ```float* foo``` rather than ```float *foo``` +4. Avoid unnecessary use of ```typedef```. Use ```struct foo {}``` instead of ```typedef struct {} foo;``` +5. All definitions should be namespaced. Core Signaletic functions, structs, enums, variable definitions, etc. begin with the prefix ```sig_```. +6. Provide a ```struct sig_Status``` as the last argument to any function that may cause errors + +Stylistic conventions very often raise [bike shed](https://www.bikeshed.org/) issues for communities. While these may not be your preferred choices, hopefully we can all agree to disagree. If you find that you are having trouble satisfying one or more conventions, or if you think a stylistic change is warranted, please feel free to raise it in a way that is respectful of the sometimes distracting and polarizing nature of such debates. diff --git a/README.md b/README.md index 139eb07..74641e5 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,14 @@ On the Daisy platform, Signaletic is compiled using Daisy's own toolchain, which On the Web, Signaletic is compiled using the Emscripten compiler toolchain. +## Respecting Open Source Labour + +Signaletic is offered as open source software for you to use and modify within a culture of reciprocity. It is built by volunteers, who take time out of their personal and family lives to share their work and enthusiasm with a community of peers. Please respect this labour by contributing your own time, resources, and energies in whatever form you can offer. This might be as simple as sharing artwork or projects you've made with Signaletic, by contributing code and documentation, or by respectfully filing bug reports and feature requests. + +Many open source contributors have experienced burnout because of unrealistic or asymmetrical expectations by some community members, particularly those who are being paid for their time spent using the project but don't contribute directly to it. While it's important and rewarding for us to help out with your projects, an immediate response to issues, problems, questions, or bugs often isn't feasible. + +If you're using Signaletic in a commercial project, in a large grant-funded artwork, or as an essential component in your academic teaching or research, please consider sharing financial support or your own labour with the Signaletic community. + ## Attribution Signaletic is developed by Colin Clark and is licenced under the [MIT License](LICENSE). From 8c457e43479c87a5a75ad2b8f8d0a86c935356e7 Mon Sep 17 00:00:00 2001 From: Colin Clark Date: Fri, 14 Oct 2022 14:42:39 -0400 Subject: [PATCH 2/3] gh-54: Adds a guideline about intellectual property and licenses. --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da6fc41..5a04a91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,7 @@ In general, pull requests should: 2. Include tests verifying the changes (see below). 4. Update or add markdown documentation for API changes. 5. Provide documentation for new functions. +6. Contain only your own original creative work, or the work of other authors who are clearly attributed (with links) that is shared under a compatible open source license (please ask if in doubt) #### Commit Messages From 8c07090629e2a999638a72fd88def8dbb06c58a8 Mon Sep 17 00:00:00 2001 From: Colin Clark Date: Fri, 14 Oct 2022 14:46:19 -0400 Subject: [PATCH 3/3] gh-54: Tweaks whitespace and minor wording. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 74641e5..fe6626a 100644 --- a/README.md +++ b/README.md @@ -98,9 +98,9 @@ On the Web, Signaletic is compiled using the Emscripten compiler toolchain. ## Respecting Open Source Labour -Signaletic is offered as open source software for you to use and modify within a culture of reciprocity. It is built by volunteers, who take time out of their personal and family lives to share their work and enthusiasm with a community of peers. Please respect this labour by contributing your own time, resources, and energies in whatever form you can offer. This might be as simple as sharing artwork or projects you've made with Signaletic, by contributing code and documentation, or by respectfully filing bug reports and feature requests. +Signaletic is offered as open source software for you to use and modify within a culture of reciprocity. It is built by volunteers, who take time out of their personal and family lives to share their work and enthusiasm with a community of peers. Please respect this labour by contributing your own time, resources, and energies in whatever form you can offer. This might be as simple as sharing artwork or projects you've made with Signaletic, by contributing code and documentation, or by respectfully filing bug reports and feature requests. -Many open source contributors have experienced burnout because of unrealistic or asymmetrical expectations by some community members, particularly those who are being paid for their time spent using the project but don't contribute directly to it. While it's important and rewarding for us to help out with your projects, an immediate response to issues, problems, questions, or bugs often isn't feasible. +Many open source contributors have experienced burnout because of unrealistic or asymmetrical expectations by some community members, particularly those who are being paid for their time spent using the project but don't contribute back to it. While it's important and rewarding for us to help out with your projects, an immediate response to issues, problems, questions, or bugs often isn't feasible. If you're using Signaletic in a commercial project, in a large grant-funded artwork, or as an essential component in your academic teaching or research, please consider sharing financial support or your own labour with the Signaletic community.