|
| 1 | +# Contributing to GitVersion |
| 2 | +We love contributions to get started contributing you might need: |
| 3 | + |
| 4 | + - [Get started with git](http://rogerdudler.github.io/git-guide) |
| 5 | + - [How to create a pull request](https://help.github.com/articles/using-pull-requests) |
| 6 | + - [An issue to work on](https://github.com/ParticularLabs/GitVersion/labels/up-for-grabs) - We are on [Up for grabs](http://up-for-grabs.net/), our up for grabs issues are tagged `up-for-grabs` |
| 7 | + - An understanding of our [architecture](#architecture) and how [we write tests](#writing-tests) |
| 8 | + |
| 9 | +Once you know how to create a pull request and have an issue to work on, just post a comment saying you will work on it. |
| 10 | +If you end up not being able to complete the task, please post another comment so others can pick it up. |
| 11 | + |
| 12 | +Issues are also welcome, [failing tests](#writing-tests) are even more welcome. |
| 13 | + |
| 14 | +# Architecture |
| 15 | +GitVersion has two distict steps for calculating versions in v3.0. |
| 16 | + |
| 17 | +1. A set of strategies are evaluated to decide on the base version and some metadata about that version. |
| 18 | + These strategies include HighestReachableTag, NextVersionInConfig, MergedBranchWithVersion, VersionInBranchName etc. |
| 19 | +2. The highest base version is selected, using that base version the new version is calculated. |
| 20 | + |
| 21 | +Visually it looks something like this: |
| 22 | + |
| 23 | + |
| 24 | +[Edit Diagram](http://www.plantuml.com/plantuml/form?url=http://www.plantuml.com/plantuml/png/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea_0G00) |
| 25 | + |
| 26 | +## Base Version Strategies |
| 27 | +Currently we have the following strategies |
| 28 | + |
| 29 | + - `HighestTagBaseVersionStrategy` - Finds the highest reachable tag from the current branch |
| 30 | + - `VersionInBranchBaseVersionStrategy` - Extracts version information from the branch name. eg `release/3.0.0` will find `3.0.0` |
| 31 | + - `ConfigNextVersionBaseVersionStrategy` - Returns the version from the GitVersion.yaml file |
| 32 | + - `MergeMessageBaseVersionStrategy` - Finds version numbers from merge messages. eg. `Merge 'release/3.0.0' into 'master'` will return `3.0.0` |
| 33 | + - `FallbackBaseVersionStrategy` - Always returns 0.1.0 for new repositories |
| 34 | + |
| 35 | +Each strategy needs to return an instance of `BaseVersion` which has the following properties |
| 36 | + |
| 37 | + - `Source` - Description of the source. eg `Merge message 'Merge 'release/3.0.0' into 'master'' |
| 38 | + - `ShouldIncrement` - Some strategies should have the version incremented, others do not. eg `ConfigNextVersionBaseVersionStrategy` returns false, `HighestTagBaseVersionStrategy` returns true |
| 39 | + - `SemanticVersion` - SemVer of the base version strategy |
| 40 | + - `BaseVersionSource` - Sha of the source. Commits will be counted from this Sha. Can be null (eg ConfigNextVersionBaseVersionStrategy returns null) |
| 41 | + - `BranchNameOverride` - When `useBranchNameAsTag` is used, this allows the branch name to be changed by a base version. |
| 42 | + VersionInBranchBaseVersionStrategy uses this to strip out anything before the first - or /. So `foo` ends up being evaluated as `foo`. If in doubt, just use null |
| 43 | + |
| 44 | +# Writing Tests |
| 45 | +We have made it super easy to write tests in GitVersion. Most tests you are interested in are in `GitVersionCore.Tests\IntegrationTests`. |
| 46 | + |
| 47 | +There is a scenario class for each type of branch. For example MasterScenarios, FeatureBranchScenarios etc. |
| 48 | + |
| 49 | +## 1. Find Appropriate Scenario class |
| 50 | +Find where your issue would logically sit. Or create a new scenario class if it doesn't fit anywhere in particular. |
| 51 | + |
| 52 | +## 2. Create a test method |
| 53 | +We are currently using NUnit, so just create a descriptive test method and attribute it with `[Test]` |
| 54 | + |
| 55 | +## 3. Use a fixture |
| 56 | +We have a few fixtures for different scenarios. |
| 57 | + |
| 58 | + - `EmptyRepositoryFixture` - Gives you an empty git repo to start with |
| 59 | + - `RemoteRepositoryFixture` - A local repo tracking a test remote repository. The remote repo is available through the `Repository` property, the local is accessible via `LocalRepository` |
| 60 | + - `BaseGitFlowRepositoryFixture` - A repo setup for GitFlow (has a develop branch checked out ready to go) |
| 61 | + |
| 62 | +You can use a fixture by just `using` it. Like this |
| 63 | +``` csharp |
| 64 | +using (var fixture = new EmptyRepositoryFixture(new Config())) |
| 65 | +{ |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +## 4. Customise config |
| 70 | +If you are using non-default configuration just modify the `Config` class before creating the fixture |
| 71 | + |
| 72 | +## 5. Writing the scenario |
| 73 | +We have a number of extension method off `IRepository` to make it easy to write tests at the flow level and not worry about creating/commiting files. |
| 74 | + |
| 75 | +An example test looks like this: |
| 76 | +``` csharp |
| 77 | +fixture.Repository.MakeATaggedCommit("1.0.0"); |
| 78 | +fixture.Repository.CreateBranch("feature-test"); |
| 79 | +fixture.Repository.Checkout("feature-test"); |
| 80 | +fixture.Repository.MakeACommit(); |
| 81 | +fixture.Repository.MakeCommits(4); |
| 82 | + |
| 83 | +fixture.AssertFullSemver("1.0.1-test.1+5"); |
| 84 | +``` |
| 85 | + |
| 86 | +The last line is the most important. `AssertFullSemver` will run GitVersion and assert that the full SemVer it calculates is what you expect. |
| 87 | + |
| 88 | +## 6. Submit a pull request with the failing test |
| 89 | +Even better include the fix, but a failing test is a great start |
0 commit comments