Versioning with signed packages is always a bit of a pain. It’s made things harder to deal with when I release new versions. Thanks to Simon Cropp, I was introduce to JSON.net's model for version numbers which solves it. You can read all about it here, but here’s the short version
ApprovalTests & ApprovalUtilities will be v 3.0 from here on out.
Nuget Version numbers will be actual version, and will continue to evolve.
I found that asp.net pages were giving me some issues with generated keys, so I added a scrubber you can use if you need to. You can view the code here.
.gitattributes suggestions
Line endings are a pain for everyone, but git’s solution of switching them makes things worse for ApprovalTests. Fortunately, Jake Ginnivan came up with a very nice solution of setting the approved files to binary with removes this problem. Simply add:
*.approved.* binary
to your .gitattributes [Contributors: Jake Ginnivan]
Over the last 2 weeks I have be fortunate enough to pair with Simon Cropp for about 8 hours on my open source project ApprovalTests. Simon has taught me a lot about running a better open source project, this blog is an attempt to share some of that for those not fortunate enough to be able to pair with Simon themselves.
Think about your 'brand'
Often I am writing ApprovalTests because I use ApprovalTests myself. I am happy that others find it useful as well and believe in sharing and open source, so I also make it an open source project. However, all of my thinking goes into after a programmer has it on their computer. However, there is a lot of things that happen before someone has ApprovalTests on their computer. Most of what I am about to talk about is specific to this area of open source. In the 8 hours we paired, we spent surprising little time actually programming C#.
It works on my computer
I believe this is particularly harder with .Net than other languages. There were many things that I just assumed everyone had because I never thought I did a special installed for them. Some of these were libraries that were put in my Global Assembly Cache (GAC) by VisualStudio (2010) but not by (2012). That means adding .dll's which means configuring git.
Git and binary files
I really wish then was a simple header to all files indicating that they are a binary or text file. There isn't. This becomes an issue with git, so if you are checking in binary files, you need to set your .gitattributes to include them. For example, I added the following to my .gitattributes:
#Binary
*.dll binary
*.exe binary
*.png binary
*.tif binary
*.tiff binary
*.snk binary
*.ttf binary
If you don't do this as soon as someone clones your repo, there will already be changes.
I'm pretty good about cleaning my code, but what about my project in general? All though references you don't use anymore? That Silverlight experiment? Even dll's that are in your project but no longer referenced by your project. All of that makes it harder for someone else to clone and play with your source.
Consistency
This project started before nuget, so there were dll's that were added directly that now should be added by nuget. It's hard to remember the advantage of consistency in a project, especially as it is not bothering you. This is a double edged sword with pairing. On the one hand it's easy to code because you have your environment setup plus already know the tricks. On the other hand, it masks trouble that a lone programmer will have with your source.
Version Numbers and Signed Code
This is a long post, but the short version is that in the end I followed JSON.net's model for version numbers. This means that while the nuget version number will increase, the version number for ApprovalTests will now remain at 1.22 for all time. Because I sign ApprovalTests, this allows me better compatibility with other software.
Version Numbers & Simple Builds
An other problem was getting a single place for the version numbers. This required a bit of awesome hacking on Simon's part. Here's the high level view
create a solution level file for the version number
add it to packages via link (there is a drop down on add)
Manually change your .csproj file to move it into your properties folder Properties\VersionInfo.cs
Use this when creating your nuget with the -Version flag
Having more than one dll file in a nuget package is a bit counter productive since you now can't use only 1 of them. In my case I had 2, so now I have two nuget packages: ApprovalTests & ApprovalUtilities. Of course, ApprovalTest depends on ApprovalUtilities, but you can now use the Utilities on it's own, as originally intended.
Think long term
On the Internet things live forever. Whenever possible link to a domain you control that can move with you. When I started everything was on sourceforge, now I have moved to github and links I have posted will be broken because of that. That history that creeps into your project isn't just in you code. Your brand is the full experience. Blogs, videos, stackoverflow questions, packages, repos, code, api's. Try to make it still work 5 years from now.
More to come...
This blog is already getting pretty long, and there is still much more Simon as got me thinking about. Here's my current todo list:
Continuous Integration Server - I'm a big believer in this on regular projects but it seemed like overkill when I was the only committer. I just had to remember to always run my tests. But there is an other advantage here. I keeps me aware of at least 2 machines, meaning it will be easier to think of other people who clone the repo.
Website - On top of moving the website to github, and using a static website generator like jekyll. I am also aware of needing to structure my website to guide people to Understanding the Code, Using the Code, and Browsing the Code. A very nice example of this in the NancyFx Page.
Documentation - This includes what goes in the blog vs into a wiki. The main difference being that wiki should be relevant next year, while a blog is relevant NOW and not so important next year.
Again, a super big thanks for all the help Simon has given me. I have paired with more than 50 people across the globe and all of them have been very helpful to me. Simon had a particular gift for understanding the branding of an open source project and was very patience working with me to improve ApprovalTests.
Text Files will now work with UTF with (many/most) Diff
Tools. This basically comes down to making everything UTF8, and including the
bom (byte order mark) header in the text files.
**Backwards compatibility break**
This change means
version22 of ApprovalTests will break compatibility with previous versions.
To adjust for this,
when you run your tests, ApprovalTests will check the .approved file and add
the UTF8 bom if needed. This might result in you needing to re-check-in your
approved file, despite an apparent lack of change.
While not strictly a feature of v.22, this version marks the
move of the source to GitHub. (https://github.com/approvals/ApprovalTests.Net/)
This should make it easier for people to branch and play around with the code.
Although my preferred method of collaboration is still a remote pair
programming session via skype. If you are interesting in pairing just ping me
on twitter @LlewellynFalco
We have added the
Interface DatabaseAdaptor, which makes it much easier to do IExecutableQuery
type approvals. This is based on the ‘Testing the Weather’ pattern.
XUnit supports testing of methods using the async and await
keywords. Now ApprovalTests supports it as well. Asynchronous parallel
programming offers many advantages with both IO and multicore, and it’s great
to see this paradigm opening up so nicely in the .net world.
It’s always been a source of problems detecting where
different systems have placed the Diff Reporter programs ApprovalTests
uses. Thanks to the addition of
“where.exe” on windows7 and above, if the reporter is in your system path, it
will now be found. This comes with the addition of P4Merge in the reporter
options. P4Merge will also diff images giving us yet another excellent option.
This is not the same as a portable library (that’s also on
the list) but it does help with language portability. Meaning if you are using
.Net but not using C#, ApprovalTests is looking out for you.
Contributors
A big thanks to everyone who contributed! I could not have
done a ¼ of what I have if it wasn’t for the people who have paired with me
(They have also allowed 2 new ports of ApprovalTests in the last iteration as
well to Node.js & Perl).
ApprovalTests has always relied on the pairing of contributors,
and I was remiss for not being more vocal about it in the past. Thanks again
for all your help.
