Skip to content

Latest commit

 

History

History
114 lines (73 loc) · 6.85 KB

CONTRIBUTING.adoc

File metadata and controls

114 lines (73 loc) · 6.85 KB
Raw

Contributing to Eclipse uProtocol

Thanks for your interest in this project. Contributions are welcome!

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

Getting Started

Eclipse Account

First thing you need to do before contributing is to create an account with the Eclipse Foundation. Once your account is created, you will need to sign the Eclipse Contributor Agreement (ECA). Lastly, you will need to create a GitHub account if you do not already have one and then link your GitHub account to your Eclipse Foundation account.

Getting Engaged with uProtocol Development

Best way to get engaged and contribute are to:

Weekly Zoom Meeting

The uProtocol community meets regularly on Zoom calls covering different focus areas. Please refer to the Eclipse-SDV Community Calendar for details.

Join Zoom Meeting https://eclipse.zoom.us/j/87919934501?pwd=7CI4VuAIRNq4pstQbFtHhb8mM0XwQR.1 Meeting ID: 879 1993 4501 Passcode: 640538

Best Current Practices (BCPs)

The following section will elaborate on the best practices we (the contributor community) will apply to each repositories in the Eclipse-uProtocol project.

  • Projects that are intended to be used in production MUST adhere to BCPs listed below.

If the project is not intended to be used for production:

  • MUST clearly labeled in your repos README.adoc as NOT INTENDED FOR PRODUCTION USE

Code Reviews

Code reviews MUST be performed by at least one committer before a pull request can be merged.

Reviewers SHOULD make suggestions in lieu of comments, for issues found in a pull request following GitHub’s guidelines.

Commits & Pull Requests

Below are the requirements for a commit (or set of commits) to be merged into the main branch:

  • Commit messages and pull request descriptions, MUST contain a well described summary description followed by detailed description of the change

  • New features/functions SHOULD have an associated GitHub issue linked in the pull request

  • Developer facing API MUST have full descriptive documentation

  • Non-developer facing APIs, SHOULD have full descriptive documentation

  • SHOULD have 100% test coverage

  • MUST update the projects README.adoc if any of the instructions to build or use the software has changed

  • Pull Requests MUST NOT be merged till all reviewer’s comments and/or suggestions have been acknowledged by the commit author or reviewer, either by accepting, rejecting (with explanation), or filing a separate issue for unresolved comments and/or suggestions.

Repositories

The following are BCPs for newly created repositories under the Eclipse-uProtocol project:

  • GitHub actions MUST be used to create CI/CD workflows for validating build, test, and documentation for every pull request for main branch

  • "Branch Protection Rules" MUST be enabled with the minimal settings below (replace verify-pr for the target that runs the build, test, and documentation workflows):

branch_protection_rules: [
        orgs.newBranchProtectionRule('main') {
          required_approving_review_count: 1,
          required_status_checks+: [
            "verify-pr"
          ],
        },
      ],

If NOTICE information cannot be autogenerated: * MUST include NOTICE.adoc

  • SHOULD have a software testing framework (tools) that can measure test code coverage (ex. jacoco, gtest, ctest, etc…​)

Why Apache 2.0 and not MIT or BSD?

The Apache 2.0 License and the MIT License are both popular open-source licenses, but they have some differences in terms of their requirements and provisions. Here are the key distinctions:

  • Scope: The Apache 2.0 License is more comprehensive and covers patents, trademarks, and attribution requirements, while the MIT License is simpler and primarily focuses on copyright.

  • Patent Grant: The Apache 2.0 License includes a patent grant, which means that it provides explicit permission for users to use any patents held by the licensor. The MIT License does not include a specific patent grant.

  • Redistribution: Both licenses allow for the redistribution of the software, but the Apache 2.0 License includes specific requirements for preserving notices, disclaimers, and license terms in derivative works.

  • Copyleft: The MIT License is considered a permissive license, allowing for more flexibility in how the software is used and integrated into other projects. The Apache 2.0 License has some copyleft provisions, requiring modifications and derivative works to be licensed under the same license.

  • Compatibility: Both licenses are generally considered compatible with other open-source licenses. However, the Apache 2.0 License is more explicitly compatible with the GNU General Public License (GPL) version 3, while the MIT License is compatible with a wider range of licenses.

Contact

Contact the project developers via the project’s "dev" list or on slack.