Skip to content

Contributing

Jump to bottom
Piotr Puszkiewicz edited this page Mar 13, 2015 · 3 revisions

General Vipr Contributing Guide

  1. Make sure that there is a corresponding issue for your change first. If there is none, create one, unless the change is truly trivial.
  2. Create a fork in GitHub
  3. Create a branch off the master branch. Give it a name, such as issue-123 or githubhandle-issue-123 that makes it easy to see what the branch is used for. Having an issue-specific branch also makes it easier to isolate your change from incoming changes from the origin.
  4. Commit your changes and push your changes to GitHub
  5. Create a pull request against the origin's master branch

DOs and DON'Ts

  • DO follow the project's coding style (see below)
  • 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 surprise us with big pull requests. Instead, file 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 MIT or Apache 2 licensed code that you think is a good fit to add to Vipr, file an issue and start a discussion before proceeding.

C# Coding Style

The general rule we follow is "use Visual Studio defaults".

  1. Use Allman style braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be indented on its own line and it must not be nested in other statement blocks that use braces.
  2. Use four spaces of indentation (no tabs).
  3. Use _camelCase private members and use readonly where possible. Prefix instance fields with _, static fields with s_ and thread static fields with t_.
  4. Avoid this. unless absolutely necessary.
  5. Always specify the visibility, even if it's the default (i.e. private string _foo not string _foo).
  6. Specify namespace imports at the top of the file, outside of namespace declarations. Sort them alphabetically, with System. namespaces at the top and blank lines between different top level groups.
  7. Avoid more than one empty line. For example, do not have two blank lines between members of a type.
  8. Avoid extra spaces. For example avoid if (someVar == 0)..., where the dots mark the extra spaces. If you're using Visual Studio, consider enabling "View White Space (Ctrl+E, S)" to aid detection.
  9. Use language keywords instead of BCL types (i.e. int, string, float instead of Int32, String, Single, etc) for both type references and method calls (i.e. int.Parse instead of Int32.Parse).

Test Coding Style

  1. Create a test project for each assembly. If you are creating both Unit Tests and Integration Tests then split them into two test projects. The test projects should live in a common folder whose name is Tests
  2. Tests should follow the Given-When-Then convention in naming tests. The Given statement is captured in the test class name and the When-Then is captured in test method names.
  3. Use Fluent Assertions where possible to define test expectations.

Commits

Format commit messages as follows (based on this excellent post):

Summarize the 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.

If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format
below.

Fix #42

Factor commits appropriately, i.e not too large or 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 pull request.

#Issues

If you are looking at getting your feet wet with some simple (but still beneficial) changes, check out the list of Up-for-grabs issues.

You do not need to file an issue for trivial changes (e.g. typo fixes). Just send a PR if it's tiny.

If an issue is complex, consider filing the issue and giving the project team time to respond before sending a corresponding pull request. If you want to work on the issue in the meantime, let us know in the issue thread. Giving us a chance to review the issue will help save time if, for example, about particular implementation constraints that you should know or if we know why existing behavior can't be changed.

Don't feel obliged to match every issue with a pull request. Simply filing issues for problems you encounter is a great way to contribute too!

Licensing

  • DO NOT submit pull requests that alter licensing related files or headers. If you believe there's a problem with them, file an issue and let us take care of it.
Clone this wiki locally