Skip to content

Latest commit

 

History

History
91 lines (66 loc) · 5.66 KB

CONTRIBUTING.md

File metadata and controls

91 lines (66 loc) · 5.66 KB

How to contribute

First of all, thank you for wanting to contribute to NFluent! There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

Contribution can take many forms

  1. Starring the repo (as a token of support)
  2. Opening an issue
  3. Commenting an issue
  4. Opening a PR with bug fixes
  5. Opening a PR with new features
  6. Helping with code review

Opening an Issue

Reported issues are assessed rapidly and fix in a timely manner if identified as important. Note that feedback on error messages are welcomed. When reporting an issue in Git, please fill all present fields. Quality of our response depends on your effort!

Request for new checks When you ask that we had a new assertion logic, please provide an example or a use case, it will help us understand the purpose of the check.

Working on the code base

Prerequisite

  • As of September 2019, we use Visual Studio 2019 Community Edition. We strongly advise you do the same.
  • You need to have support for T4 templates. You need to install 'Visual Studio Add-In development' pack with the VS 2017 installer.
  • You need the NUnit3 adapter in order to run tests from the IDE, or R#.
  • You need the Nuget CLI in your path; you can download the latest version here here.
  • We recommend having R# and NCrunch installed, but those are not prerequisites.
  • The build script depends on Python 2.x (https://www.python.org/downloads/). But only NFluent team members needs it as it is used for publishing coverage data to CodeCov.io

Initial Steps

  1. Fork on GitHub
  2. Make sure your line-endings are configured correctly
  3. Clone your fork locally
  4. Configure the upstream repo (git remote add upstream git://github.com/tpierrain/NFluent)
  5. Create a local branch (git checkout -b myBranch)
  6. Work on your feature, following the NFluent Definition of Done (DoD) for Development.
  7. Run a local build to verify everything is ok. Use the CI file; this lau,ch a CI cycle. If you have test errors, you need to fix them. Reach for us if you encounter issues (documentation may not be up to date, or the build script may have unwanted dependencies).
  8. Rebase if required (see below)
  9. Push the branch up to GitHub (git push origin myBranch)
  10. Send a Pull Request on GitHub

You should never work on a clone of master, and you should never send a pull request from master - always from a branch. The reasons for this are detailed below.

Solution organization

  • As a general rule, we are happy with the current project organization. Thanks for keeping it as is, or raise an issue if you see a compelling reason for change.
  • Tests projects are located in the 'tests' folder
  • Main source files are in the 'Src' folder
  • Per framework specific build projects are located in the 'Platforms' subfolder to tackle cross compatility.
  • You should add your tests to the NFluent.Tests shared project.
  • You must add your code to the Nfluent shared project.
  • The NFluent.Generated and NFluent.Tests.Generated are derived from IntCheckExtensions, SignedIntCheckExtensions, DoubleCheckExtensions and related tests. If you alter any of those files, use the 'Transform All T4 Templates' command from the build menu. This will regenerate checks and tests for other numerical types.

Handling Updates from Upstream/Master

While you're working away in your branch it's quite possible that your upstream master (most likely the canonical NFluent version) may be updated. If this happens you should:

  1. Stash any un-committed changes you need to
  2. git checkout master
  3. git pull upstream master
  4. git checkout myBranch
  5. git rebase master myBranch
  6. git push origin master - (optional) this this makes sure your remote master is up to date

This ensures that your history is "clean" i.e. you have one branch off from master followed by your changes in a straight line. Failing to do this ends up with several "messy" merges in your history, which we don't want. This is the reason why you should always work in a branch and you should never be working in, or sending pull requests from, master.

If you're working on a long running feature then you may want to do this quite often, rather than run the risk of potential merge issues further down the line.

Sending a Pull Request

First of all, check that your code is in line with the NFluent Definition of Done (DoD) for Development.

For NCrunch users, please refers to the NCrunch configuration tips for NFluent contributors.

Then, while working on your feature you may well create several branches, which is fine, but before you send a pull request you should ensure that you have rebased back to a single "Feature branch" - we care about your commits, and we care about your feature branch; but we don't care about how many or which branches you created while you were working on it :-)

When you're ready to go you should confirm that you are up to date and rebased with upstream/master (see "Handling Updates from Upstream/Master" above), and then:

  1. git push origin myBranch
  2. Send a descriptive Pull Request on GitHub - making sure you have selected the correct branch in the GitHub UI!

Disclaimer

This How to contribute procedure was mostly extracted from the awesome Nancy open source project. Thanks to them for their inspiration.