diff options
| -rw-r--r-- | CODE_OF_CONDUCT.md | 21 | ||||
| -rw-r--r-- | CODING_GUIDELINES.md | 28 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 91 | ||||
| -rw-r--r-- | CONTRIBUTOR-LICENSE-AGREEMENT.md | 37 |
4 files changed, 177 insertions, 0 deletions
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..6dd0786b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,21 @@ +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting
\ No newline at end of file diff --git a/CODING_GUIDELINES.md b/CODING_GUIDELINES.md new file mode 100644 index 00000000..39c663eb --- /dev/null +++ b/CODING_GUIDELINES.md @@ -0,0 +1,28 @@ +# Coding Guidelines + +## Code Style +Follow [Rust coding guidelines](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md). +When adding new feature or adding an API try to adhere to [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/about.html). +Avoid using unsafe code. + +## Code formatting +Always use rustfmt before you commit as your code won't pass CI pipeline if rustfmt is not applied. We adhere to default settings. + +```$ clippy fmt``` + + +## Code analysis +Clippy is used to catch common mistakes and we run it as part of our CI pipeline. + +```$ cargo clippy``` + + +## Code testing +Ideally, all code should be unit tested. Unit tests should be in module file or if the file or tests are very long in separate file `tests.rs` in the same directory as `mod.rs`. + +## Error handling +Error handling suggestions follow the [Rust book guidance](https://doc.rust-lang.org/book/ch09-00-error-handling.html). Recoverable errors should be handled with [Result](https://doc.rust-lang.org/std/result/). Our suggestions on unrecoverable errors are listed below: +* Panic (the code should not panic) +* `unwrap()` - Unwrap should only be used for mutexes (e.g. `lock().unwrap()`) and test code. For all other use cases, prefer `expect()`. The only exception is if the error message is custom-generated, in which case use `.unwrap_or_else(|| panic!("error: {}", foo))` +* `expect()` - Expect should be invoked when a system invariant is expected to be preserved. `expect()` is preferred over `unwrap()` and should contain a detailed error message on failure in most cases. +* `assert!()` - This macro is kept in both debug/release and should be used to protect invariants of the system as necessary.
\ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29b..3a454d4f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ + +# Contributing to thin-edge.io + +Thanks for taking the time to contribute to thin-edge.io! + +Contributing is not limited to writing code and submitting a PR. Feel free to submit an [issue](https://github.com/thin-edge/thin-edge.io/issues) or comment on an existing one to report a bug, provide feedback, or suggest a new feature. You can also join us on GitHub Discussions. + +Of course, contributing code is more than welcome! If you're planning to submit a PR to implement a new feature or fix a bug, please open an issue that explains the change and the motivation for it. + +If you are interested in contributing documentation, please note the following: + + +- Doc issues are labeled with the `doc` label. +- The thin-edge.io docs content is in the `docs/src/` directory. + +<br/> + +# Pull request and git commit guidance + +## Opening PRs and organizing commits + +PRs should generally address only 1 issue at a time. If you need to fix two bugs, open two separate PRs. This will keep the scope of your pull requests smaller and allow them to be reviewed and merged more quickly. + +When possible, fill out as much detail in the pull request template as is reasonable. Most important is to reference the GitHub issue that you are addressing with the PR. + +**NOTE:** GitHub has [a feature](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) that will automatically close issues referenced with a keyword (such as "Fixes") by a PR or commit once the PR/commit is merged. Don't use these keywords. We don't want issues to be automatically closed. We want our testers to independently verify and close them. + +## Writing good commit messages + +Git commit messages should explain the how and why of your change and be separated into a brief subject line followed by a more detailed body. When in doubt, follow this guide for good commit messages and you can’t go wrong: [https://chris.beams.io/posts/git-commit/](https://chris.beams.io/posts/git-commit/). + + +## Reviewing, addressing feedback, and merging + +Generally, pull requests need two approvals from maintainers to be merged. + +When addressing review feedback, it is helpful to the reviewer if additional changes are made in new commits. This allows the reviewer to easily see the delta between what they previously reviewed and the changes you added to address their feedback. + +Once a PR has the necessary approvals, it can be merged. Here’s how the merge should be handled: + + +- If the PR is a single logical commit, the merger should use the “Rebase and merge” option. This keeps the git commit history very clean and simple and eliminates noise from "merge commits." +- If the PR is more than one logical commit, the merger should use the “Create a merge commit” option. +- If the PR consists of more than one commit because the author added commits to address feedback, the commits should be squashed into a single commit (or more than one logical commit, if it is a big feature that needs more commits). This can be achieved by the “Squash and merge” option. If they do this, the merger is responsible for cleaning up the commit message according to the previously stated commit message guidance. +<br/> +<br/> +# Contributor License Agreement +We do not want to bother you with too much legalese, but there are two pages you have to read carefully, this page and the CONTRIBUTOR LICENSE AGREEMENT. + +## Signing the CONTRIBUTOR LICENSE AGREEMENT +Each Contribution to Software AG's Open Source Projects must be accompanied by a sign-off indicating acceptance of current version of the CONTRIBUTOR LICENSE AGREEMENT, which is derived from the Apache Foundation's Individual Contributor License Agreement, sign-off time stamp relates to corresponding version of the CONTRIBUTOR LICENSE AGREEMENT maintained here on GitHub as well. Sign-Off and acceptance of the CONTRIBUTOR LICENSE AGREEMENT is declared by using the option "-s" in + +> git commit -s + +which will automatically generate a sign-off statement in the form: + +> Signed-off-by: Max Mustermann \<MaxM@example.com\> + +By adding this sign-off statement, you are certifying: + +*By signing-off on this Submission, I agree to be bound by the terms of the **then current CONTRIBUTOR LICENSE AGREEMENT** located at https://github.com/thin-edge/thin-edge.io/blob/main/CONTRIBUTOR-LICENSE-AGREEMENT.md, **which I have read and understood** and I agree that this Submission constitutes a "Contribution" under this Agreement.* + +## Note on Privacy +Please note that this project and any contributions to it are public and that a record of all contributions (including any personal information submitted with it, including a sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. + +In addition to [GitHub's privacy statement](https://docs.github.com/en/github/site-policy/github-privacy-statement) extracting personal data from these projects for any other use than maintaining the projects and communication related to it is prohibited, explicitly prohibited is extracting email addresses for unsolicited bulk mails. + +If you'd like to keep your personal email address private, you can use a GitHub-provided no-reply email address as your commit email address. You can choose which verified email address to author changes with when you edit, delete, or create files or merge a pull request on GitHub. If you enabled email address privacy, then the commit author email address cannot be changed and is \<username\>@users.noreply.github.com by default. + +See [setting your commit email address on GitHub](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address#setting-your-commit-email-address-on-github). + +In the upper-right corner of any page, click your profile photo, then click **Settings**. + +1. In the left sidebar, click **Emails**. +1. In "Add email address", type your email address and click **Add**. +1. Verify your email address. +1. In the "Primary email address" list, select the email address you'd like to associate with your web-based Git operations. +1. To keep your email address private when performing web-based Git operations, click **Keep my email address private**. +1. You can use the git config command to change the email address you associate with your Git commits. + +See [setting your commit email address in Git](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address#setting-your-commit-email-address-in-git). + +1. Open Git Bash. +2. Set an email address in Git. You can use your GitHub-provided no-reply email addressor any email address. +>$ git config --global user.email "email@example.com" +3. Confirm that you have set the email address correctly in Git: +>$ git config --global user.email <br> +>email@example.com +4. Add the email address to your account on GitHub, so that your commits are attributed to you and appear in your contributions graph. + +Release date: 2021-03-29 diff --git a/CONTRIBUTOR-LICENSE-AGREEMENT.md b/CONTRIBUTOR-LICENSE-AGREEMENT.md new file mode 100644 index 00000000..3da3b122 --- /dev/null +++ b/CONTRIBUTOR-LICENSE-AGREEMENT.md @@ -0,0 +1,37 @@ +THIS CONTRIBUTOR LICENSE AGREEMENT (this “Agreement”), is effective for each Contribution by signing-off the Submission by using the option "-s" in "git commit", which will generate a sign-off statement with your user name and email address as described in [**CONTRIBUTING.md**](https://github.com/thin-edge/thin-edge.io/blob/main/CONTRIBUTING.md). + +This Agreement is for Your protection as a Contributor as well as the protection of **Software AG**. + +Except for the license granted herein, You reserve all right, title, and interest in Your Contributions. + +You accept and agree to the following terms and conditions for Your Contributions submitted to **Software AG**. + +You read, understand and follow the guidelines for the various roles You represent in **Software AG**’s opensource communities, starting with the contributor guidelines [**CONTRIBUTING.md**](https://github.com/thin-edge/thin-edge.io/blob/main/CONTRIBUTING.md). + +**“Contribution”** means any original work of authorship, including any modification of or addition to an existing work including any associated comments and documentation, that you submit to **Software AG** in any manner for inclusion in any Work. + +**“Submission”** means the act of submitting Your Contributions by You to the projects managed by **Software AG** in any form of electronic, verbal, or written communication, especially using the features of the respective source code versioning platforms. + +**“Work”** means any project, work or materials owned or managed by **Software AG**. + +**“You”** and **“Your”** means you and any organization on whose behalf you are entering this agreement. + +You represent that: + +(a) Each of Your Contributions is either Your original creation or + +(b) Your Contributions are based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license and You have the right under that license to submit that work with modifications, whether created in whole or in part by You, under the designated license and Your Submissions include complete details of any third-party license and copyright or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions. + +(c) If you act as an employee or contractor where your employer(s) or client has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make such Contributions and are legally entitled to grant the below licenses on behalf of that employer/client or that your employer/client has waived any such rights for your Contributions to **Software AG**. + +Subject to the terms and conditions of this Agreement, You hereby grant to **Software AG** a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. + +Subject to the terms and conditions of this Agreement, You hereby grant to **Software AG** and to recipients of software distributed by **Software AG** a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed. + +You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. + +You agree to notify **Software AG** of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect. + +By signing-off on my Submissions, I agree to be bound by the terms of the then current CONTRIBUTOR LICENSE AGREEMENT located at https://github.com/thin-edge/thin-edge.io/blob/main/CONTRIBUTOR-LICENSE-AGREEMENT.md, which I have read and understood and I agree that this Submission constitutes a "Contribution" under this Agreement. + +Release Date: 2021-03-29
\ No newline at end of file |