As an Open Source contributor...
I find an interesting open source project that I want to contribute to. I fork/clone the repository to my machine. Then I have to figure out how to build it.
I try something and the build fails. Do I need a certain SDK or Visual Studio feature installed? Which version?
I get it to build and then I try to run the tests. 1/3rd of them fail, because they are looking for something that isn't installed on my machine.
If I'm lucky (!?) I find a document in the repository that claims to be build instructions, but it is jumbled and clearly out of date. I try to follow it, but something I need to install is no longer available, or not compatible with my version of Windows. Will a newer version of that thing work OK?
Uggh, what a mess.
As an Open Source maintainer...
I put together a cool little project in my spare time and post it online. It's simple and straightforward to build and run tests.
Then a contributor complains that they can't build it. What information could possibly be missing? It's simple and straightforward, right? I write a small text file explaining the obvious instructions. The contributor tries to follow it but is even more confused. I don't have time for this.
Uggh, what a mess.
My solution is AppVeyor. I treat AppVeyor as the reference build environment.
- New Project, select your project.
- Settings -> Do what you need to get a green build + tests
- Settings -> Export YAML. Add it to your repo.
- Delete the AppVeyor project
- New Project again, but this time configure nothing. It will use the settings from your repo.
- Confirm that build + tests are still green
Now the instructions for how to build + run tests are in source control. Anyone can read them. There won't be any missing details. If a dependency changes, I won't miss updating the instructions, because AppVeyor will report my build is broken.
No more mess.