Skip to content

Commit 310d235

Browse files
AArnottAArnott
committed
Add a CONTRIBUTING.md file
1 parent 584f789 commit 310d235

File tree

2 files changed

+109
-0
lines changed

2 files changed

+109
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
Contributing to this project
2+
============================
3+
4+
## Prerequisites
5+
6+
This project is actively developed using the following software.
7+
It is highly recommended that anyone contributing to this library use the same
8+
software.
9+
10+
1. [Visual Studio 2015][VS]
11+
12+
### Optional additional software
13+
14+
Some projects in the Visual Studio solution require optional or 3rd party components to open.
15+
They are not required to build the full solution from the command line using MSBuild,
16+
but installing this software will facilitate an enhanced developer experience in Visual Studio.
17+
18+
1. [Node.js Tools for Visual Studio][NodeJsTools]
19+
2. [NuProj for VS2015][NuProj]
20+
21+
All other dependencies are acquired via NuGet.
22+
23+
## Building
24+
25+
To build this repository from the command line, you must first execute our init.ps1 script,
26+
which downloads NuGet.exe and uses it to restore packages.
27+
Assuming your working directory is the root directory of this git repo,
28+
and you are running Windows PowerShell, the command is:
29+
30+
.\init.ps1
31+
32+
Everything in the repo may be built via building the solution file
33+
either from Visual Studio 2015 or the command line:
34+
35+
msbuild src\Nerdbank.GitVersioning.sln
36+
37+
### Important notice when developing with Visual Studio
38+
39+
The NuGet package restore functionality in Visual Studio does not work for this project, which relies
40+
on newer functionality than comes with Visual Studio 2015 Update 3. You should disable automatic
41+
package restore on build in Visual Studio in order to build successfully and have a useful Error List
42+
while developing.
43+
44+
Follow these steps to disable automatic package restore in Visual Studio:
45+
46+
1. Tools -> Options -> NuGet Package Manager -> General
47+
2. *Clear* the checkbox for "Automatically check for missing packages during build in Visual Studio
48+
49+
With this setting, you can still execute a package restore within Visual Studio by right-clicking
50+
on the _solution_ node in Solution Explorer and clicking "Restore NuGet Packages". But do not ever
51+
execute that on this project as that will corrupt the result of `init.ps1`.
52+
53+
Before developing this project in Visual Studio, or after making project or project.json changes,
54+
or to recover after Visual Studio executes a package restore, run the `init` script again.
55+
56+
## Testing
57+
58+
The Visual Studio 2015 Test Explorer will list and execute all tests.
59+
60+
## Pull requests
61+
62+
Pull requests are welcome! They may contain additional test cases (e.g. to demonstrate a failure),
63+
and/or product changes (with bug fixes or features). All product changes should be accompanied by
64+
additional tests to cover and justify the product change unless the product change is strictly an
65+
efficiency improvement and no outwardly observable change is expected.
66+
67+
In the master branch, all tests should always pass. Added tests that fail should be marked as Skip
68+
via `[Fact(Skip = "Test does not pass yet")]` or similar message to keep our test pass rate at 100%.
69+
70+
## Self-service releases for contributors
71+
72+
As soon as you send a pull request, a build is executed and updated NuGet packages
73+
are published to this Package Feed:
74+
75+
https://ci.appveyor.com/nuget/Nerdbank.GitVersioning
76+
77+
By adding this URL to your package sources you can immediately install your version
78+
of the NuGet packages to your project. This can be done by adding a nuget.config file
79+
with the following content to the root of your project's repo:
80+
81+
```xml
82+
<?xml version="1.0" encoding="utf-8"?>
83+
<configuration>
84+
<packageSources>
85+
<add key="Nerdbank.GitVersioning CI" value="https://ci.appveyor.com/nuget/Nerdbank.GitVersioning" />
86+
</packageSources>
87+
</configuration>
88+
```
89+
90+
You can then install the package(s) while you have your new "Nerdbank.GitVersioning CI" package source selected:
91+
92+
```powershell
93+
Install-Package Nerdbank.GitVersioning -Pre -Version 0.1.41-g02f355c05d
94+
```
95+
96+
Take care to set the package version such that it exactly matches the AppVeyor build
97+
for your pull request. You can get the version number by reviewing the result of the
98+
validation build for your pull request, clicking ARTIFACTS, and noting the version
99+
of the produced packages.
100+
101+
[VS]: https://www.visualstudio.com/en-us/downloads/visual-studio-2015-downloads-vs.aspx
102+
[NuProj]: https://onedrive.live.com/redir?resid=63D0C265F96E43D!2477835&authkey=!AHh2k9FoNR-nFHo&ithint=file%2cmsi
103+
[NodeJsTools]: https://www.visualstudio.com/vs/node-js/
104+
[NuGetClient]: https://dist.nuget.org/win-x86-commandline/v3.3.0/nuget.exe

‎readme.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,9 @@ that can help you to translate between the two representations.
110110
`Get-CommitId.ps1` takes a version and print out the matching commit (or possible commits, in the exceptionally rare event of a collision).
111111
`Get-Version.ps1` prints out the version information for the git commit current at HEAD.
112112

113+
### How do I build Nerdbank.GitVersioning from source?
114+
115+
Prerequisites and build instructions are found in our
116+
[contributing guidelines](CONTRIBUTING.md).
117+
113118
[semver]: http://semver.org

0 commit comments

Comments
 (0)