Ways to Contribute
If you would like to contribute, consider these options:
Submit a bug report (for a guide on submitting good bug reports, read
Painless Bug Tracking).
- Verify fixes for bugs.
- Submit a code fix for a bug.
- Submit a feature request.
- Help answer questions in the discussions list.
- Submit a unit test.
- Tell others about the project.
- Tell the developers how much you appreciate the product!
Make sure you can build the code. Familiarize yourself with the
project guidelines and our
coding conventions. You might also read these two blogs posts on contributing code:
Open Source Contribution Etiquette by Miguel de Icaza and
Don’t “Push” Your Pull Requests by Ilya Grigorik.
Before submitting a feature or substantial code contribution please
discuss it with the team and ensure it follows the product
roadmap. Note that all code submissions will be rigorously reviewed and tested by the Katana team, and only those that meet an extremely high bar for both quality and design/roadmap appropriateness will be merged into the source.
You will need to sign a Contributor License Agreement before submitting your pull request. To complete the Contributor License Agreement (CLA), you will need to submit a request via the form and then electronically
sign the Contributor License Agreement when you receive the email containing the link to the document. This needs to only be done once for any Microsoft Open Technologies OSS project.
Configure git with a username and email address to use for your commits. Your username should be your CodePlex username, so that people will be able to relate your commits to you. From a command prompt, run the following commands:
git config user.name YourCodePlexUserName
git config user.email YourAlias@YourDomain
Then, follow these steps:
- Decide what feature or bug fix you plan to take on and start a discussion with the title of the bug so we know someone is already working on it. e.g. “I'm going to fix issue 59: Something's Broken.” If you're just starting out, pick something small to fix
- Add a missing unit test.
- Fix an FxCop issue.
- Search for a // TODO comment in the code and address one.
- Fix a defect in the issue list (search for “Proposed” items). Try something small first and work your way up to larger issues.
- Create a fork of the project.
- Clone the fork you created in the previous step to your machine.
- Checkout the 'dev' branch in your local clone
- Make the relevant changes in your local clone (potentially adding a unit test if this is a bug fix).
- Please only contribute code which you wrote or have the rights to contribute. If you do need to add 3rd party code please
discuss it with us first.
- Build the solution and make sure that there are 0 errors. Note: As part of building you may need to obtain NuGet packages from the Outercurve Foundation NuGet public feed*.
- Commit your changes in your local clone. You may end up repeating steps 4-6 multiple times as you work. When you are finished and ready to have us accept your change, go to step 8.
- Pull from the 'dev' on the main Identity repository (not your fork) into 'dev' in your clone and merge your changes with any new commits (fix any merge conflicts you might have).
- Push your changes up to your fork.
- Go to the source control tab and send a pull request. Make sure the summary contains relevant bug numbers and a good description of your changes. Pull requests should always be for the
- If you need to revise your code, then do so locally and update the review. Repeat until we approve the review.
- Wait for your review to be approved. We'll try to get to it as soon as possible. Once the review is approved, someone from the team will push your changes to the main source repository. Then you can delete your fork.
You may find the following software helpful for preparing a code contribution:
xUnit.net VS 2012 Plugin allows you to run xUnit.net tests in Visual Studio 2012.
- StyleCop can help you follow our
coding conventions. Note that we use only some StyleCop guidelines. Also, If you install StyleCop, please be sure
not to install the Visual Studio templates, as they will change your File > New Item templates in a way that will generate classes which are out of compliance with our coding conventions.
When you run a commit from the command line, if you don’t include the -m option, it will pop up a text editor for you to compose the commit message. That text editor is VIM by default. If you’re not a VI person, then you might want to set an alternative
editor. You can do so with the following command:
git config core.editor PathToYourFavoriteEditor
*By running build, you will be initiating the download of other software from a NuGet-based feed that is owned by the Outercurve Foundation. You are responsible for locating, reading and complying with the license terms that accompany each such software.
Each software that you obtain through this feed is licensed to you by its respective owner. We grant you no rights for third party software from this feed.