|
| 1 | +# Contribution Guidelines |
| 2 | + |
| 3 | +If you're reading this, you're probably thinking about contributing to this repository. We really appreciate that--thank you! |
| 4 | + |
| 5 | +This document provides guidelines on contributing to this repository. Please follow these guidelines when creating issues, making commits, and submitting pull requests. The repository maintainers review all pull requests and verify that they conform to these guidelines before approving and merging. |
| 6 | + |
| 7 | +#### Table Of Contents |
| 8 | +[How Can I Contribute?](#how-can-i-contribute) |
| 9 | + * [Contribution Ideas](#contribution-ideas) |
| 10 | + * [What should I know before I get started?](#what-should-i-know-before-i-get-started) |
| 11 | + |
| 12 | +[Licensing](#licensing) |
| 13 | + * [Developer's Certificate of Origin](#developers-certificate-of-origin) |
| 14 | + * [Sign Your Work](#sign-your-work) |
| 15 | + |
| 16 | +[Coding Conventions](#coding-conventions) |
| 17 | + |
| 18 | +[Additional Notes](#additional-notes) |
| 19 | + * [Resources](#resources) |
| 20 | + |
| 21 | +## How Can I Contribute? |
| 22 | + |
| 23 | +### Contribution Ideas |
| 24 | + |
| 25 | +1. Raise issues for bugs, features, and enhancements. |
| 26 | +1. Submit updates and improvements to the documentation. |
| 27 | +1. Submit articles and guides, which are also part of the documentation. |
| 28 | + |
| 29 | +### What should I know before I get started? |
| 30 | + |
| 31 | +The best way to directly collaborate with the project contributors is through GitHub. |
| 32 | + |
| 33 | +* If you want to raise an issue such as a defect, an enhancement request, feature request, or a general issue, please open a GitHub issue. |
| 34 | +* If you want to contribute to our code by either fixing a problem, enhancing some code, or creating a new feature, please open a GitHub pull request against the development branch. |
| 35 | +> **Note:** All pull requests require an associated issue number, must be made against the **development** branch, and require acknowledgement of the DCO. See the [Licensing](#licensing) section below. |
| 36 | +
|
| 37 | +Before you start to code, we recommend discussing your plans through a GitHub issue, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing. |
| 38 | + |
| 39 | +It is your responsibility to test and verify, prior to submitting a pull request, that your updated code doesn't introduce any bugs. Please write a clear commit message for each commit. Brief messages are fine for small changes, but bigger changes warrant a little more detail (at least a few sentences). |
| 40 | +Note that all patches from all contributors get reviewed. |
| 41 | +After a pull request is made, other contributors will offer feedback. If the patch passes review, a maintainer will accept it with a comment. |
| 42 | +When a pull request fails review, the author is expected to update the pull request to address the issue until it passes review and the pull request merges successfully. |
| 43 | + |
| 44 | +At least one review from a maintainer is required for all patches. |
| 45 | + |
| 46 | +### Contribution Guidelines |
| 47 | +This repo is maintained on a best-effort basis. The burden is on the submitter and not the repo maintainers to ensure the following criteria are met when code is submitted. |
| 48 | +1. All code submissions must adhere to the structure of the repo: |
| 49 | + * Lower-level functions and API calls must be saved in the /pyedgeconnect folder. |
| 50 | + * Do not create new separate folders for submitted projects. |
| 51 | + * Do not make copies of existing files to be saved in different folders. |
| 52 | + * The objective is that all submissions build on the repo as a whole, rather than creating multiple sub-projects housed in the repo. |
| 53 | +1. All Python code should conform to PEP-8 standards. The maintainers use black & flake8 to perform this check. That does not require submitters to use these tools, but regardless of the code editor used, the PEP-8 check must be successful. |
| 54 | +1. All functions should have explanatory docstrings using the reStructuredText format. |
| 55 | +1. All git commits should have clear, concise messages which explain the changes made in the commit. All Pull Requests (PRs) should contain a title and comments that explain the impact of the PR. |
| 56 | +1. All code submitted for merge consideration must be tested by the submitter. |
| 57 | + |
| 58 | +## Licensing |
| 59 | + |
| 60 | +All contributions must include acceptance of the DCO: |
| 61 | + |
| 62 | +### Developer’s Certificate of Origin |
| 63 | + |
| 64 | +> Developer Certificate of Origin Version 1.1 |
| 65 | +> |
| 66 | +> Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 660 |
| 67 | +> York Street, Suite 102, San Francisco, CA 94110 USA |
| 68 | +> |
| 69 | +> Everyone is permitted to copy and distribute verbatim copies of this |
| 70 | +> license document, but changing it is not allowed. |
| 71 | +> |
| 72 | +> Developer's Certificate of Origin 1.1 |
| 73 | +> |
| 74 | +> By making a contribution to this project, I certify that: |
| 75 | +> |
| 76 | +> \(a) The contribution was created in whole or in part by me and I have |
| 77 | +> the right to submit it under the open source license indicated in the |
| 78 | +> file; or |
| 79 | +> |
| 80 | +> \(b) The contribution is based upon previous work that, to the best of my |
| 81 | +> knowledge, is covered under an appropriate open source license and I |
| 82 | +> have the right under that license to submit that work with |
| 83 | +> modifications, whether created in whole or in part by me, under the same |
| 84 | +> open source license (unless I am permitted to submit under a different |
| 85 | +> license), as indicated in the file; or |
| 86 | +> |
| 87 | +> \(c) The contribution was provided directly to me by some other person |
| 88 | +> who certified (a), (b) or (c) and I have not modified it. |
| 89 | +> |
| 90 | +> \(d) I understand and agree that this project and the contribution are |
| 91 | +> public and that a record of the contribution (including all personal |
| 92 | +> information I submit with it, including my sign-off) is maintained |
| 93 | +> indefinitely and may be redistributed consistent with this project or |
| 94 | +> the open source license(s) involved. |
| 95 | +
|
| 96 | +### Sign Your Work |
| 97 | + |
| 98 | +To accept the DCO, simply add this line to each commit message with your |
| 99 | +name and email address (`git commit -s` will do this for you): |
| 100 | + |
| 101 | + Signed-off-by: Jane Example <jane@example.com> |
| 102 | + |
| 103 | +For legal reasons, no anonymous or pseudonymous contributions are |
| 104 | +accepted. |
| 105 | + |
| 106 | +## Coding Conventions |
| 107 | + |
| 108 | +1. Python code should conform to PEP-8. PyCharm editor has a built-in PEP-8 checker. |
| 109 | +1. Since this is a collaborative project, document your code with comments that will help other contributors understand the code you write. |
| 110 | +1. When in doubt, follow conventions you see used in the source already. |
| 111 | + |
| 112 | +## Additional Notes |
| 113 | + |
| 114 | +> **Note:** Please don't file an issue to ask a question. Please reach out to us via email or disucssion forums. |
0 commit comments