Skip to content

Contributing

Jump to bottom
Sridhar Periyasamy edited this page Mar 12, 2015 · 3 revisions

General Vipr Contributing Guide

  1. Unless it is a trivial change, make sure that there is a corresponding issue for your change first. If there is none, create one.
  2. Create a fork in GitHub
  3. Create a branch off the master branch. Name it something that that makes sense, such as issue-123 or githubhandle-issue-123. This makes it easy for everyone to figure out what the branch is used for. It 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 our 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. We 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 properly indented on its own line and it must not be nested in other statement blocks that use braces.
  2. We use four spaces of indentation (no tabs).
  3. We use _camelCase private members and use readonly where possible. Prefix instance fields with _, static fields with s_ and thread static fields with t_.
  4. We avoid this. unless absolutely necessary.
  5. We always specify the visibility, even if it's the default (i.e. private string _foo not string _foo).
  6. Namespace imports should be specified at the top of the file, outside of namespace declarations and should be sorted alphabetically, with System. namespaces at the top and blank lines between different top level groups.
  7. Avoid more than one empty line at any time. For example, do not have two blank lines between members of a type.
  8. Avoid spurious free spaces. For example avoid if (someVar == 0)..., where the dots mark the spurious free spaces. Consider enabling "View White Space (Ctrl+E, S)" if using Visual Studio, to aid detection.
  9. We use language keywords instead of BCL types (i.e. int, string, float instead of Int32, String, Single, etc) for both type references as well as method calls (i.e. int.Parse instead of Int32.Parse).

Test Coding Style

  1. We create a test project for each assembly in our solution. If 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. We follow a 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. We use Fluent Assertions where possible to define test expectations.

Commits

Please format 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.

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

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.

#Issues

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

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

If an issue is complex, consider filing it and giving us time to respond before sending a corresponding PR. If you want to work on the issue, just let it be known on the issue thread. Giving us a chance to review the issue will help save time. For example, we might let you know why existing behavior can't be changed or about particular implementation constraints you need to keep in mind, etc.

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

Licensing

  • DO NOT submit PRs 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