Skip to content

Latest commit

 

History

History
128 lines (78 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

128 lines (78 loc) · 6.75 KB
Raw

Contribution guidelines for Rules Framework

Contribution to Rules.Framework is deeply appreciated as we evolve this project to serve the purpose of providing a easy to use, configurable and extensible rules framework for everyone, but some ground guidelines must be ensured to have everyone aligned and allow the usage of some automation on top of this repository.

Found a bug, what to do?

First of all, search existent issues for any open issue with the bug you found, it might have been already reported. If you find a matching issue for your bug, you can subscribe notifications for it and/or complement with additional information in the comments section.

If you don't see a matching issue, please go ahead and create a new one. Make sure you include the following information on issue description:

  • OS (Windows, Ubuntu, Mac, etc)
  • .Net SDK version you are using
  • Exception message and stack trace (when applicable)
  • A repro of the issue (optional, but can be requested later)

New feature request/improvement

It might a good idea to first take a look at all open issues w/ enhancement tag before opening a new feature request or improvement. If you are:

  • Requesting a new feature with widespread impacts on whole solution and you want to implement it - please submit a new issue with a design proposal so that we can discuss it before proceeding with the implementation.
  • Requesting a new feature with small changes on codebase or a improvement - please submit a new issue and you can provide a implementation for it.
  • Only requesting a new feature or a improvement - please submit a new issue.

Whatever you want to do, please make sure to outline sample usage scenarios so that everyone understands your intended usage scenarios.

I want to contribute

First of all, ensure you have appropriate .Net SDK installed (need .Net Core 3.1 and .Net Standard 2.0) and ensure you have a MongoDB instance running locally at port 27017.

  1. Fork repository.

  2. Clone repository locally.

  3. Create a new branch.

    git checkout -b my-branch

  4. Create a .env file to adjust specific settings for your local environment. Use the .env_template as a starting point.

  5. Perform your code changes, including covering unit tests and integration tests.

  6. [Windows Environment] After your code changes are done, under a PowerShell terminal and located at local repository root, run:

    .\run-tests.ps1

    Open <your-repo-root>/coverage-outputs/report/index.html on your favorite browser to preview HTML coverage report.

  7. Commit your changes to codebase - make sure you use conventional commits specification (changelog will be supported sometime in the future, and this will be important to use automatic tooling on top of commit messages).

  8. Push changes to your forked repository remote.

    git push origin my-branch

  9. Open a pull request with your changes targeting to Farfetch/rules-framework:master. Link any issues solved on the pull request.

  10. Changes will automatically run through GitHub actions build (build + test) for your pull request. Also, Codacy will detect the pull request and subsequent changes, and will perform static analysis on changes. Please make sure all checks are green on pull request.

  11. Changes might be suggested or requested. If that happens, please make sure to have all tests passing after changes are done.

  12. Please do not merge incoming changes from master branch, perform a rebase instead.

    git fetch upstream master:master
git rebase master -i
git push --force origin master

After all designated reviewers accept the changes (a contributor will set the reviewers), changes will be merged to master.

Code rules

To keep source code clean and comprehensive, please make sure you follow these rules of thumb:

  • Public classes, structures, interfaces, properties and methods must be documented. Private, protected and internal ones are excluded from this rule.

  • Usings must be placed inside namespace. System usings always come first.

  • Any warning suppression must be added to global suppression files, and a justification is mandatory.

  • Implicit variable declarations (using var) instead of explicit declarations should be preferred, to avoid redundancy and allow for more flexible and better readable code.

  • Unit tests are separated per each class - suppose you are testing class Rule, you should place all tests for its' members under RuleTests.

  • Unit tests naming must be done under the pattern MemberName_Conditions_ExpectedOutcome. See examples above for guidance.

    // RuleTests.cs
public void NewRule_GivenRuleWithStringConditionTypeAndContainsOperator_BuildsAndReturnsRule() { }

// RuleBuilderExtensionsTests.cs
public void WithSerializedContent_GivenNullContentSerializationProvider_ThrowsArgumentNullException() { }

  • Unit tests body structure must follow the Arrange, Act & Assert pattern.

  • Solution line coverage must be kept over 90% at all times.

  • [ExcludeFromCodeCoverage] can be used exceptionally where used dependencies of class are difficult to test. Make sure your design makes the best effort to abstract these dependencies to promote testability before considering using this attribute.

Commit rules

Commit rules follow as baseline the conventional commits specification, to allow the build of automation over commit messages.

All commit messages should use following rules:

  • Do not capitalize message first letter.
  • Do not place a dot '.' at the end.
  • Specify imperative and present tense messages (e.g. "fix rules evaluation").

Allowed types

  • ci: affecting build or continuous integration systems.
  • docs: changes to documentation.
  • feat: addition of new features.
  • fix: solving bugs.
  • refactor: changes to source code that do not solve a bug or add a new feature.
  • test: adding new tests or fixing failing tests.
  • chore: a change on the repository's contents that does not affect production code nor does fit on the previously described types.

Documentation rules

If source code changes affect a documented functionality or technical documentation, documentation must be updated on pull request with those changes. If the code changes add a new functionality and none of the existent documentation is affected, it is not required to document new functionality under same pull request, although it should be done at some point in time.