Contributing - update licensing and tips

docs/reference/contributing/guidelines/guidelines.md

@@ -1,10 +1,44 @@
-## Contributing guidelines
+## Contributing to Mbed OS
 
-Consistency is an important aspect of a codebase. To ensure consistency in Mbed OS code, we have created contributing guidelines. Any contribution to Mbed OS needs to meet the following criteria:
+Mbed OS is an open source, device software ecosystem for the internet of things. Contributions are an important part of the ecosystem and our goal is to make it as simple as possible to become a contributor. 
 
-- Design and coding style: Be consistent with your changes. We define software design principles and coding style in [this document](../contributing/style.html).
-- Contributions guidance: The process and how we review contributions is described in the [workflow](../contributing/workflow.html) document.
-- Licenses: Licenses should comply with the [licenses described here](../contributing/license.html).
+Contributions can be made to source code and documentation. Both are developed on Github. Mbed uses the same open source license for contributions (inbound) as is used for the license to the project (outbound). Our default and preferred software license is Apache License version 2.0 (Apache-2.0). 
+
+To encourage frictionless collaboration, as well as robust, consistent, and maintainable code, we have built up a set of guidelines for contributing to Mbed. 
+
+### Types of contributions  
+
+There are a few categories a contribution may fall under. Each type has different risks and benefits. When contributing, it’s important to not mix types and instread create multiple contributions if needed. Once a contribution is accepted it will appear in the next release based on type of contribution.  
+
+The type of contribution will impact how it is incorporated into Mbed OS, as explained [here](../contributing/workflow.html)
+
+### How to contribute  
+
+Mbed OS has a team of people called maintainers who will help move contributions along, providing guidance and direction. This team is responsible for helping you get your changes in, as well as controlling the overall quality and consistency of the software. Contributions are accepted in the form of pull requests. Before any contributions are accepted to any Mbed OS software, there must be a review by at least one other developer experienced with the functionality. For contributions that span multiple functionalities, multiple reviewers may be necessary. Once reviewed the changes will be tested as part of a larger system. The testing includes but is not limited to: functional correctness, static analysis, integration with other parts of the system, code style or formatting and regressions such as code size increase or performance degredation. If any of the testing fails, more work will be needed before the contribution is accepted.
+
+### Licensing  
+
+A license is the contract between the author permitting the use of software to others. It specifies what you can and cannot do when receiving the software. It provides protection for both the user and owner of the software. In an Mbed project, the full terms of the license can be found in a file named LICENSE. Additionally, all source files must contain the SPDX identifier as a comment at the beginning of the file.  
+
+Note that one repository may contain multiple, independent codebases, each with their own license. If you are integrating two libraries with different licenses, it is important that each library retains its original license. In the case of a repository having software with multiple licenses, the contribution will be made according to the license of the file the contribution modifies. By creating a pull request on GitHub, you are agreeing to license your contributions under the same license as the original code. Is commonly reffered to as "inbound=outbound". This enables contributions to happen in a quick and effortless way and encourages collaboration.  
+
+Most Mbed OS software is licensed under a permissive license. The three most common permissive licenses are:  
+- Apache 2.0  
+- BSD 3-Clause  
+- MIT
+
+For new Mbed projects, we suggest adopting the Apache 2.0 license. Note that any Mbed software release under a permissive license cannot accept any code that is licensed under a "copyleft" license. Doing so would prevent us from continuing to distribute our code under the permissive license. You are welcome to use Mbed software with copyleft licenses, as long as the rules of the copyleft license are followed.  
+
+A more detailed description on licenses can be found in the [guidelines/contributing](../contributing/guidelines/license.html).
+
+### Tips  
+
+- The maintainers and reviewers are your friends. At times, programming can be very personal. However, it's important to realize that we all share a common goal, and that honest feedback is constructive feedback. 
+- Larger contributions take longer to be accepted than smaller contributions. The best contributions are small and purposeful, achieving a single goal. You may be asked to split up a contribution if it contains multiple unrelated changes. 
+- Consistency is an important aspect of a codebase. To ensure consistency in Mbed OS code, we have created contributing guidelines. Any contribution to Mbed OS needs to meet the following criteria:
+    - Design and coding style: Be consistent with your changes.  The existing style of a codebase overrules any personal preference. We define software design principles and coding style in [this document](../contributing/style.html).
+    - Contributions guidance: The process and how we review contributions is described in the [workflow](../contributing/workflow.html) document.
+    - Licenses: Licenses should comply with the [licenses described here](../contributing/license.html).
 
 ### Access to the ARMmbed organization on GitHub
 

docs/reference/contributing/guidelines/workflow.md

@@ -93,13 +93,13 @@ We consider the following pull request types.
 
 #### Fix
 
-A bug fix is a backward-compatible internal change that fixes incorrect behavior.
+A bug fix is a change that fixes a specific defect in the codebase with backwards compatibility. These are the highest priority because of the positive impact the change will have on users developing against the same code. A bug fix should be limited to restoring the documented or proven otherwise, originally intended behavior. Bug fixes are candidates for patch releases. Large, non-trivial bug fixes approaching the size of refactors run the risk of being considered refactors themselves.
 
 Release: patch
 
 #### Refactor
 
-Refactors are intended for feature releases, if they are not fixing specific issues, because they can introduce new issues.
+A refactor is a contribution that modifies the codebase without fixing a bug or changing the existing behavior. Examples of this would be moving functions or variables between translation units, renaming source files or folders, scope modification for nonpublic code, documentation structure changes, and test organization changes. There is always the risk that someone depended on the location or name before a refactor therefore these are lower in priority than bug fixes and might require detailed justification for the change. Refactors are candidates for feature releases. 
 
 Release: feature
 
@@ -109,11 +109,11 @@ Updating target implementation (adding a new target or updating already supporte
 
 Release: patch
 
-#### Feature
+#### Functionality change
 
-New features target feature releases. A new feature can only be integrated if the feature supports most of the targets (if it requires new target HAL implementation).
+Any change in the functionality, it can be adding a new feature, adding a new method or a function. Software language does not matter.
 
-We consider adding a new functionality to be a feature. It does not matter if it is C++, C or Python.
+A feature contribution contains a new API, capability or behavior. It does not break backwards compatibility with existing APIs, capabilities or behaviors. New feature contributions are very welcome in Mbed OS. However, because they add capability to the codebase, it's easy for a new feature to introduce bugs and a support burden. The introduction of new features should also come with documentation, majority of targets support and comprehensive test coverage proving the correctness of the feature per the documentation. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases. 
 
 Release: feature
 
@@ -133,6 +133,8 @@ Release: patch
 
 A breaking change is any change that results in breaking user space. It should have strong justification for us to consider it. Often, such changes can be backward compatible, for example, deprecating the old functionality and introducing the new replacement.
 
+A contribution containing a breaking change is the most difficult PR to get merged. Any breaking changes in a codebase can have a large negative impact on any users of the codebase. Breaking changes are always limited to a major version release.
+
 Release: major
 
 ### Pull request template