Add a technical spec that describes a project standard

[jszwedko]

Mostly just the ossmanifesto with descriptions of each component.

After iterating until we are happy, I think we should make sure our own projects adhere to this, then discuss with the core team, and finally share with the brigade.

[jasonlally]

@jszwedko I like this and I like the approach too of rolling it out on internal projects. While we're at it, we can make sure the sf crime data project adheres as well, it's a simple enough project, might as well start it off on the right foot.

On another note, I understand semver conceptually and functionally how to tag releases. But the overall approach may be worth a workshop or 30 minute Q&A even with project leads. I think what I struggle with is I want to do it right and I get hung up on how to define different releases. I think it's somewhat an art and practice that's harder to glean off of someone else's code or by reading about semver. Despite semver being very rational and well-defined, people and organizations are messier :-)

This is somewhat technical, but I think is more about project management, clear expectations, communication and practice. I think getting project leads to understand how to use semver as a tool for communicating both the history of a project as well as using it in conjunction with short, agile releases could go far to institutionalize and strengthen best practices at the Brigade.

Anyway, those are just some of my thoughts for the future, but doesn't affect anything right now.

[jszwedko]

@jasonlally Good points about semvar, that is probably the most complicated piece of this. It is especially difficult to do with things like web apps where the interface is pretty ambiguous.

[therebelrobot]

@jasonlally @jszwedko: for sure about the workshop. We need one on github, on semver, on documentation... Maybe a good chance for NDoCH?

[therebelrobot]

@jszwedko I would also add that any project that adhere's to this spec should list so in their README with a link back to this spec. Maybe a shields.io badge?

example:

[jszwedko]

That is a great idea, will add the shield.

[jasonlally]

Nice! I love this.

By the way, in terms of semver, I actually like what http://keepachangelog.com/ has to say about this, which is to just be clear about whether one is using semver or not. Maybe it's better to be light-handed here and to make the standard about a clear, consistent changelog with versions one could reason about? Maybe we strive for semver as appropriate, but don't let that make you fail passing the project spec?

Some critiques on semver:
http://www.jongleberry.com/semver-has-failed-us.html
https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e

P.S. I love the way Olivier Lacan wrote up http://keepachangelog.com/ It's just so reasonable and thoughtful and not overly opinionated.

[jszwedko]

I agree that the critiques have valid points, but semantic versioning remains the "best" approach that I have seen proposed so far. That being said, I'm cool with backing off from strictly requiring semantic versioning in lieu of requiring that the project document their versioning strategy.

[therebelrobot]

@jasonlally: the issue that was being addressed in jashkenas' gist is outlined more fully in this issue: jashkenas/underscore#1805 - Which basically shows that he, as a developer, doesn't want to play by the open community's rules of engagement when it comes to releases, making his product less stable, and requiring more effort from adopters to implement his software confidently. I don't think that spurring the community, nor the additional dismissive comments he made in that thread, should be an example we should hold up for our brigade.

As for the arguments against versions < 1, I would actually agree. We're running into a similar issue on brigadehub in that all alpha and beta releases are being released as pre-releases, which is a flat number which is assumed to break for whoever uses it. To be fair, once we hit live in mid september, it'll be easier to manage semver since the api will be more or less stable, but the pre-release issue is still worth discussion for sure.

That being said, if the only issue we have with semantic versioning is pre-releases, it's my opinion that we should require semver for any code we publish, as it will give a clear distinction to adopters about the stability of the software they're adopting. It's a small, easy to implement standard, that saves a lot of headache in the long run.

[therebelrobot]

One last thing I would include in this standard is ensuring that a code of conduct is included in every project (contributor covenant is a good example)

[therebelrobot]

Also, for sure, training on semver would be an excellent use of infrastructure effort. Will definitely start gathering resources for that.

[jasonlally]

@therebelrobot - yeah, I guess I should have made sure to be clearer that I didn't mean to imply agreement or disagreement with either of those posts. Rather that there are folks that have challenges (for right or wrong reasons) and I want to be mindful that as an organization we provide the right level of guidance and that project groups don't get stuck on the wrong challenges at the wrong time.

It's ultimately an opportunity for education and "shaping the path." That's what you're doing with the training and materials. I have complete faith that we're approaching this the appropriate way.

Also, I like the idea of a contributor covenant/code of conduct (it mirrors what we're doing for the organization). It helps address the "bad actor" problem and separates that out from issues of misunderstanding or needing additional guidance.

One little implementation detail would be when that training or materials exist having a little call to action on the guidance that points them in the right direction. Could just be a "reach out to x on Slack, if you have questions about the spec" or "log an issue on this repo," or whatever channel is most appropriate.

[jszwedko]

Added code of conduct to the list in 2c5e090 -- good idea @therebelrobot

I'm in agreement with @jasonlally that we should be considerate about the level structure we put in place, focusing on values rather than the means i.e. things like "have a code of conduct" rather than "use the contributor covenant as your code of conduct". I think versioning can be approached the same way saying "document your versioning process" rather than "use semantic versioning".

Good note about how to reach out regarding the spec -- I'll leave that for when we introduce it to the larger org (which will probably be a PR to the current site or brigadehub depending on where we are pushing people to at the time).