Keeping a working spec for complex changes

Dec 28, 2011 at 10:27 PM

One thing that I think we can improve is how pull requests are discussed. Right now, this is being done via discussions. The problem is that discussions can get really long, and the specific plans often evolve throughout the discussion. This makes it very hard to just come in and see what it's about.

The case in point is this thread about all the work @thargy has been doing. In fact, there are 4 or 5 other threads about variants of the topic, making things even more difficult to follow.

Instead, it would make a lot more sense to keep a working spec with the latest plans. Then as a result of the discussion, the author would update that spec so it is always up to date. Someone who comes in late should be able to read through that and get a good idea about what the change is about without having to read through all the comments.

In order to achieve this, we can maybe just rely on the fact that discussion entries can be edited by the author. So the first entry in the discussion thread would be the 'spec', and the rest would discuss it. The author would be responsible for keeping that initial post updated with the latest.

Thoughts?

Coordinator
Dec 29, 2011 at 12:54 AM

This is the workflow we've sort of been following: http://nuget.codeplex.com/wikipage?title=Specs

The problem though is that you have to be added as an Editor to the NuGet project to create and edit wiki pages in CodePlex. I guess we could do that for anyone who wants to write specs, but it gets unwieldly.

We probably need a better approach. I was thinking we could simply use gists. Anyone can create one and we could link to it from the discussion. Any other ideas for where specs should be maintained?

Coordinator
Dec 29, 2011 at 12:56 AM

Another idea is to simply have the first message in a discussion serve as the working spec. The only problem with this is the person who started the thread is the only one who can edit the first message. That might not work well. :(

Dec 29, 2011 at 1:25 AM
haacked wrote:

Another idea is to simply have the first message in a discussion serve as the working spec. The only problem with this is the person who started the thread is the only one who can edit the first message. That might not work well. :(

I take it you didn't read the last paragraph of my post, as that's exactly what I suggested. :)

I agree that's not perfect, but it's still a step forward from where we are today. I'm of course open to alternative wiki-list solutions. gist doesn't seem like a great choice as it has no Preview support while editing (as far as I can see). If you get that fixed on github, it might be an option! ;)

Dec 29, 2011 at 8:00 AM

I'm not sure that editing the first post idea is a good idea.  A discussion is a discussion not a spec.  Overwriting the first post isn't so bad if the first post is very short and doesn't say very much, and the spec is short.

If the first post is long and detailed, then the chances are the spec is also going to be long and detailed.  So you either prepend the spec and get a ridiculously long first post - making accessing the discussion painful - or you overwrite it and lose the introductory base that kicked off the discussion - which is bad because the following comments will be out of context and unintelligible.

CodePlex is already a pain, there's discussions, issues, fork comments, code annotations, pull requests.  For a single change there's 3 or 4 places to be updated to ensure it doesn't get missed, so it pains me to suggest that the Wiki seems the right place for a spec... but it does.  At least on a wiki there's more collaboration, change control, etc.

Not everything needs a detailed spec. so maybe when a discussion leads to a spec. a coordinator creates a spec page and moves the discussion to the spec and sets the author as an editor on that page (is that even possible on codeplex?).

Dec 29, 2011 at 8:00 AM

Of course even that seems like way too much effort, so maybe editing the post is the way to go :(

Dec 29, 2011 at 8:12 AM

You know workitems have a 'Wiki link' which currently appears to not do anything... is there an option to automatically create wikipages for workitems in codeplex?

Dec 29, 2011 at 9:50 PM

My main point here was primarily about agreeing on using working specs for big changes. The exact way we do that is somewhat secondary, and in the short term, it's fine if various people use different things.

e.g. a Gist, a public Google Doc or Office 365 doc, some random other wiki-like thing, etc... Maybe it's not a big deal if only the main author can edit it, as they are the one responsible for maintaining that spec alongside their proposed code changes,

Dec 30, 2011 at 6:59 AM
thargy wrote:

You know workitems have a 'Wiki link' which currently appears to not do anything... is there an option to automatically create wikipages for workitems in codeplex?

Just saw this comment. I had never noticed this before, but I suspect it means something different: it simply gives the wiki markup that you have to use to create a link to this bug from a wiki page. Though it would be nice if that had that!