The nanoFramework team maintains several guidelines for contributing to the nanoFramework repos, which are provided below. Many of these are straightforward, while others may seem subjective. A nanoFramework team member will be happy to explain why a guideline is defined as it is.
- General Contribution Guidance describes general contribution guidance, including more subjective stylistic guidelines.
- Contribution Bar describes the bar that the team uses to accept changes.
- Contribution Workflow describes the workflow that the team uses for considering and accepting changes.
- Copyright Notice describes file header copyright notice format.
There are several issues to keep in mind when making a change.
Typos are embarrassing! We will accept most PRs that fix typos. In order to make it easier to review your PR, please focus on a given component with your fixes or on one type of typo across the entire repository. If it's going to take >30 mins to review your PR, then we will probably ask you to split it into smaller chunks.
For PRs we have templates setup, please make sure to follow them. Tick the appropriate boxes and remove what's not meant to be there. Failure to do this can lead to our nfbot closing your PR automatically.
Please format your commit messages as follows (based on this excellent post):
Summarize change in 50 characters or less
Provide more detail after the first line. Leave one blank line below the
summary and wrap all lines at 72 characters or less.
Do not include in your commit messages any keywords to close issues or PRs. These should be handled in the PR commit message.
Also do your best to factor commits appropriately, i.e not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits. If there was some accidental reformatting or whitespace changes during the course of your commits, please rebase them away before submitting the PR.
- DO follow our C/C++ coding style
- DO follow our C# coding style
- DO give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
- DO include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
- DO keep the discussions focused. When a new or related topic comes up it's often better to create new issue than to side track the discussion.
- DO blog and tweet (or whatever) about your contributions, frequently!
- DON'T send PRs for style changes.
- DON'T surprise us with big pull requests. Instead, open an issue and start a discussion so we can agree on a direction before you invest a large amount of time.
- DON'T commit code that you didn't write. If you find code that you think is a good fit to add to nanoFramework, open an issue and start a discussion before proceeding.
- DON'T submit PRs that alter licensing related files or headers. If you believe there's a problem with them, open an issue and we'll be happy to discuss it.
- DON'T add API additions without opening an issue and discussing with us first. See [API Review Process]).
Project maintainers will merge changes that align with project priorities and/or improve the product significantly for a broad set of apps. Proposals must also satisfy the published guidelines for nanoFramework.
Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risks. Changes to the codebase must first be reviewed and tested to ensure they are correct and fit for purpose and will not inadvertently break applications. We may revert changes if they are found to introduce undesired states at a later date.
We encourage adding support for other platforms and/or microcontroller units including new vendors and families. Currently there are ports for a number of STM32 based mcu's, ESP32 and TI and have a lot of momentum behind them. Ports have a weaker contribution bar, since they do not contribute to compatibility risk with existing products. For ports, we are primarily looking for functionally correct implementations.
The general plan is to have relevant targets as references. This is to keep the main repository as clean as possible and focused on common code. New reference targets can be added if deemed relevant and other can be removed if they are not that interesting anymore.
There is a repository that holds targets contributed by the community. The goal is to keep a collection of reference targets to help developers working on new ports. If you are working on supporting a new board, we encourage you to share your port there.
There is another repository that holds drivers, utilities and code patterns contributed by the community. The goal is to keep a collection of useful code and pointers to useful and handy code for developers coding with nanoFramework. If you have something that can useful for others or stumble on something that's relevant, we encourage you to share it there.
The following copyright notice header is used for all new files of original works:
//
// Copyright (c) 2017 The nanoFramework project contributors
// See LICENSE file in the project root for full license information.
//
For a file that is either a modification of an existing .NET Micro Framework file or was created by copying portions of one or more .NET Micro Framework files, the original notice has to be retained in the following format:
//
// Copyright (c) 2017 The nanoFramework project contributors
// Portions << original copyright >>
// See LICENSE file in the project root for full license information.
//
There are several copyright notices in .NET Micro Framework code base,
so for example << original copyright >> may take the form:
Copyright (c) Microsoft Corporation. All rights reserved.
(Note the extra space before All)
or
Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.
nanoFramework uses some files from other projects, typically where a binary distribution does not exist or would be inconvenient.
The following rules must be followed for PRs that include files from another project:
- The license of the file is permissive.
- The license of the file is left intact.
- The contribution is correctly attributed in the 3rd party notices file in the repository, as needed.
There are many good algorithms implemented in other languages that would benefit the nanoFramework project. The rules for porting a Java file to C# , for example, are the same as would be used for copying the same file, as described above.
Clean-room implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea.
You must sign the nanoFramework Contribution License Agreement (CLA) before your PR can merged. This is a one-time requirement for projects maintained under the nanoFramework organization. You can read more about Contribution License Agreements (CLA) on Wikipedia.