[Idea] Using plain text files as inputs to SRN

[shiftkey]

As I start using this across some projects I find myself creating a HISTORY.md file at the root to represent the rolling history (so it looks more like a Markdown document). See this file for an example.

I see that your parser is only interested in one level of headers, which makes me think I'm doing it wrong (having multiple releases and other metadata in this one file).

The other option for this scenario is to have a folder called docs\releases\ (ermagherd worlds colliding perhaps?) which contains all of the releases done so far. Like this file

So this workflow springs to mind:

• start a release by creating a file named docs\releases\A.B.md
• make some changes to the code
• edit the release notes file to indicate what was fixed
• commit and push those changes to the build server
• build server create binaries based on the largest "version" found - A.B.N (N is an incrementing number)
• build server generates the SRN release notes using a parser
• build scripts create package A.B.N by merge the SRN output with package metadata and binaries
• publish the package to users

What are your thoughts on this scenario?

[avanderhoorn]

Huge thanks for kicking off the feedback!

The currently parser certainly isn't complete or a work of beauty. The current code that we have was the bare minimum that I thought we would need to demonstrate the point and get the interactive textbox working (hence why you are probably having issue #1).

This was done as we wanted to get something out there to see if people thought we were crazy or onto something. If the former, we haven't wasted too much time, if the latter, things might change enough given the feedback, that any parser we wrote, would need to be rewritten.

I image that once we get enough feedback and turn around that we have a syntax version that works as a feasible first cut, we would create the first reference parser.

Does that make sense?

In terms of you idea, I completely understand and agree with the workflow you have put forward, and it happens to be something we did think about but don't currently have a solution for. If you have a look on the site page, go to the Syntax section and you will see 2 parts called Release and Project.

Release: As SRN allows for many releases to be defined within the one block of text, the system needs to provide a means by which an individual release can be identified. This is indicated via a standard Markdown header.

Project: As SRN allows for many projects with many releases to be defined within the one block of text, the system needs to provide a means by which an individual release can be identified. This is indicated via a standard Markdown header.

The idea would be to have one content block (i.e. a file) that could be just one release, multiple releases or multiple projects with multiple releases. If you scroll to the bottom of that Syntax section you will see I go into more details - also if you view source you will see I was playing around with some possibilities, but didn't have anything I was happy with yet.

Like you, I was thinking that using headers at different levels would feel natural but I wasn't sure exactly how this would play out.

For instance, should we just look to see if a block has one level of headers and if it does we interpret the level one headers as sections (like we currently do). Then, if we have two levels, that means we have multiple releases containing sections, hence level one is now release and level two is now sections. The problem with this though, is how we tell the difference when a user intends a given block to have no sections. In this case, what does a level one now mean.

One alternative which is safer but I feel is less natural, is to say, by convention, level one headers are always projects, level two is always release and level three is always section. This works well in cases where you have all three at play but feels a bit unnatural if you just have one block/file per release and you are trying to define sections.

The solution you put forward about having multiple files would totally work with what we "currently" have, but do you think its too much to enforce on someone? If we could figure out a way of making either scenario work (i.e. one file for everything vs multiple), it would give the developer the freedom choose which approach they liked.

What do you think? Have any other ideas of what might be possible?

[shiftkey]

I image that once we get enough feedback and turn around that we have a syntax version that works as a feasible first cut, we would create the first reference parser.

Does that make sense?

That's fine, put that stuff aside for now.

Regarding Release and Project semantics, after doing some thinking on this I keep leaning towards these two rules:

• the KISS principle
• leverage source control (you're using source control, right? 😄 )

What do I mean by this?

While I love the idea of using Markdown headers to signify nesting project/release entities in the one file, my gut says there's a couple of drawbacks...

Complexity Increases

So I need to understand the semantics of what each # represents? And if I type the wrong number the whole semantics of the document go out of wack?

Sure, they cascade down from 1 -> 3 based on their intent (but 4 isn't covered so who know what behaviour that might do), but there's a lot of assumed knowledge there about using the right number of hashes for the right context.

I say: throw that out.

Use a single # to represent the sections, and that's it. If you use more than 1, the parser doesn't care. You use sections or you don't. Let's not throw more concepts on top of that because we want the convenience of doing it all in one file

I'm happy with what you've got currently, for everything below a release.

Collaboration between developers

So I have one file to rule them all, and I have a big team of developers working on this project.

How do I manage them integrating all these changes while development is occurring?

• do new releases start from the top? Or from the bottom?
• how about i go and edit that line from an old release? you didn't notice i did it wrong because everyone's editing it as well?
• I'm bugfixing XYZ release and I forgot to update the release note but no-one noticed so the testers never see that issue has been closed...

Basically, this smells like a recipe for disaster and losing details. Don't let them shoot themselves in the foot.

An epiphany (not really)

So after more angst and sleepless nights (not really) I had a moment of enlightenment.

I'm not writing a Markdown document

I was so hung up on writing this thing out like a Markdown document that I didn't focus on what I was doing. Writing notes for others to consume. So I dropped the notion of one-file-to-rule-them-all and thought about a simpler structure.

So without using the M-word, let me describe how I'd solve this problem:

• one file per release - as a developer will know what version they're working on (bugfix, new feature, etc)
• one folder per project - as a project is a collection of releases

And then each release follows the conventions defined for:

• sections (representing a component or feature or area)
• summary (could be used on a version or on a section)
• items (a thing that happened - just some formatted text)
• category (cross-cutting concern which could be applied to any item)
• priority (cross-cutting concern which could be applied to any item)

So I've got a brain dump of how to leverage semantic versions to represent releases, and then have that flow into the rest of your project (not short-term stuff, but relates to duchess and documentation in general).

Am I getting warmer yet? 😉

[avanderhoorn]

I think you right on the money here. One thing we liked about what we originally conceived with SRN is the simplicity of what we had. Releases and project never really felt like a natural fit and hence why we didn't have it included.

It occurs to me that the idea of having a file per individual releas and a folder per project isn't really the concern of the parser. It the concern of what ever leverages the parser. To date we have steared clear of describing what this entity is and whether SRN conventions should extend to it. At the moment SRN has the parser and the formatter. This new entity would be the processor. I kind of like the idea that these components are compo sable and you can chose if you want to use them all or just parts.

More ideas to come, have to go now.

[shiftkey]

+1 to discussing this "processor" concept.

Given you're using semver to label a releases, why let people over-complicate them? Using a filename to represent the version makes it easy to succeed (and tooling can help guide you down that path).

On the Project side of things, I'm happy to leave this open for another discussion. With this concept you could represent folder names to represent each project but I haven't got a codebase handy (or some existing release notes from old projects) for me to compare how this might look.

[avanderhoorn]

I agree about using the file names as the version numbers. I think convention is key to most of this being easy and logical. I still think it would be interesting to see if we can find a way of parsing a block of text that has multiple versions in it. I agree about our earlier assertion of keeping it simple with the heading being sections but it would cool if it could deal with that case.

Agreed with leaving the Project to the side for the moment. I think it was originally conceived as a idea and a what if.

Lastly, I think the idea of having the three pillars of SRN is fairly compelling - Processor, Parser, Formatter. Each one of these should be interchangeable and should be able to run independently. As an example of a processor, we may have once processor that pulls together details from GitHub to generate a release note, vs another which is slightly different that pulls the release notes from Nuget.

[shiftkey]

I think convention is key to most of this being easy and logical.

I've got some ideas for tooling where we stick to major.minor releases for a codebase (and then integrating with source code from there) but that likely won't work if you want to dictate versions. See this page for details.

I still think it would be interesting to see if we can find a way of parsing a block of text that has multiple versions in it.

After starting down that path, I'm not sure of this. Can you elaborate on the benefits that you see of doing this (contrasting the risks I explained earlier)?

I think the idea of having the three pillars of SRN is fairly compelling - Processor, Parser, Formatter.

Agreed.

we may have once processor that pulls together details from GitHub to generate a release note

I need to write a prototype for what i just hand-crafted for the MahApps.Metro release notes (run a command against the repository, then grab data from the GitHub API, and format).

Might be a good use case for this scenario.

another which is slightly different that pulls the release notes from Nuget.

What did you have in mind for this?

[avanderhoorn]

where we stick to major.minor

How do you see this fitting into SemVer?

I still think it would be interesting to see if we can find a way of parsing a block of text that has multiple versions in it.

I think the thought that gets me is that there are project out there that have one big release.txt, and that we can try and shift those projects or facilitate them working. Maybe we just tell them to move with the times?

I think the idea of having the three pillars of SRN is fairly compelling - Processor, Parser, Formatter.

I think the next version of the site that goes out post this round of updates should make this clear.

I need to write a prototype for what i just hand-crafted for the MahApps.Metro

Really cool

another which is slightly different that pulls the release notes from Nuget.

That it would go to the nuget feed and be able to pull out the release details and pass it onto the parser. In the case of GitHub, it needs to go through the issues and build of the note and then pass it onto the parse. Same end result, just built up in different ways depending on the source.

Note, in the case of Nuget, there is nothing to stop the GitHub processor being the one that makes the note to go into the package for a given release and things stop there (i.e. composition of these pillars at work). then the Nuget processor could be used to pull out the details from a given feed, run the parser and then run the formatter.