Add new pattern for Release Process/Published Artifacts

[dgrizzanti]

Suggestion for this pattern would be to live under Begin -> Project Setup once it moved to "Structured". Looking for feedback and/or suggestions on what else folks would like to see expanded here. I can add more detail to those section as needed. Thanks!

[spier]

Thanks for submitting this pattern @dgrizzanti.

Could you move the pattern file to folder patterns/1-initial?

We typically add most patterns in that level/maturity as a start, and then improve the pattern through multiple reviews in order to level it up :) Basically getting more eyeballs onto the pattern over time.

I will take a closer look at this in the coming days.

[dicortazar]

Some general comments on the current pattern

[spier]

@dgrizzanti feel free to work in the feedback from @dicortazar first, and the resolve the respective comment threads.

If you were to move the file now, I suspect that the inline comments might not work 100% properly any more. Not sure though.

Feel free to try, either way we will learn something about GitHub reviews here :)

[spier]

I finally had time to take a closer look at your pattern.

It looks pretty good overall already, thanks for sharing this with us.

With a couple of changes we could merge this as an Initial pattern already, as that will make it easier for interested readers to discover it, which in turn will help us to improve this pattern over time.

I had some general thoughts/questions about this pattern. Curious to hear what you think:

• how are release notes tied to the artifacts? would it make it easier to write the pattern if the pattern was only about one of these things, or do they together so naturally that you cannot talk about one without also talking about the other?
• does this pattern exclusively help with getting teams to adopt an InnerSource project? Or does it also help with contributions and cross-team collaboration? If the latter, then we could add this to the Resulting Context for example.
• does it matter for this pattern if the given InnerSource project is a library, a module, a web app, or something else? or are the instructions in the pattern always applicable, no matter what type of project we are looking at?

Overall I really like that this pattern is fairly short at this point.
In the inline comments you will see that my suggestions are focused on extending it "just enough" so that it becomes easier for readers to understand what you mean.

Thanks again for your contribution!

[spier]

Suggested change

	The common code in the shared repository doesn't have a published artifact or publicly viewable release process.
	When a team is deciding whether or not to use an InnerSource projects, one of their considerations is whether they trust that they can rely on the given project for an extended period. Switching the tools/projects that they are using has a cost, so they only want to make those investments sporadically.
	It reduces trust if the given InnerSource projects doesn't have a published artifact or publicly viewable release process, as the team won't know when they can expect new features or the next release, how breaking changes are handled, etc.

I would elaborate on the Problem section a bit. e.g. what specifically is the problem about an unclear release process or missing artifacts? In which situations do the teams need those? It is fine to repeat parts of the Patlet, as the Patlet is a summary of the whole pattern.

One way that helps me think about the Problem section is "Why is this a problem"? e.g. in your case somebody might argue that release notes are not necessary. How would you convince that missing release notes are indeed a problem?

I left some ideas in the suggestion but this just represents what I am guessing what you mean. So feel free to change this entirely :)

[spier]

Suggested change

	- Release notes generated by CI system at build time
	- Release notes generated by CI system at build time

How do good release notes look like? Do you have an example that you could share here?
The example could also be from an open source project if you like.

One could also provide some sort of template for such release notes, similar to the templates provided in this pattern: https://patterns.innersourcecommons.org/p/base-documentation (this one is a good pattern to use as reference for your pattern, as they seem similar in nature)

Feel free to leave any of this for future improvements to this pattern, as I don't want to introduce unnecessary scope creep :)

[dgrizzanti]

I'll add a link to an to example to help drive the context (a project with an example of releases + release notes)

[dgrizzanti]

Added an example in the latest updated

[dgrizzanti]

• how are release notes tied to the artifacts? would it make it easier to write the pattern if the pattern was only about one of these things, or do they together so naturally that you cannot talk about one without also talking about the other?

I think the release notes are more tied to the "release" than to the artifact. I pulled in your suggestion on "Published Releases and Published Artifacts" but wondering if it would be easier to separate these. Publishing artifacts to an internal repo also bring in some "DevOps" topics so I'm thinking it could be a separate, but related pattern. Do you have any strong feelings on that?

• does this pattern exclusively help with getting teams to adopt an InnerSource project? Or does it also help with contributions and cross-team collaboration? If the latter, then we could add this to the Resulting Context for example.

I think it helps with both. If I see a project with a clear release process and/or release notes, I'm more likely to use it. Also, having an idea of release cadence and process encourage folks to contribute. I can add detail to the Resulting Context section.

• does it matter for this pattern if the given InnerSource project is a library, a module, a web app, or something else? or are the instructions in the pattern always applicable, no matter what type of project we are looking at?

It would likely only applicable to projects that are released and versioned, but I think that applies to all the types you mentioned. Release artifacts may be different depending on the type of project so that may be another reason to separate that.

Overall I really like that this pattern is fairly short at this point.
In the inline comments you will see that my suggestions are focused on extending it "just enough" so that it becomes easier for readers to understand what you mean.

Got it - I'll expand the Resulting Context context section and depending on what we decide with the published artifacts we can make additional changes.

[dgrizzanti]

Thanks for the comments @spier - let me know how you feel about splitting the release and artifacts ideas. I can see both sides but if we can to keep each on the small side, this might be worthwhile.

[spier]

Thanks for the additional input about how you are are reasoning about this pattern.

Thanks for the comments @spier - let me know how you feel about splitting the release and artifacts ideas. I can see both sides but if we can to keep each on the small side, this might be worthwhile.

I am going back and forth about this one as well.

I am leaning towards keeping it as a single pattern for now, and potentially splitting it later.
In detail:

• let's resolve the remaining open comment threads on this PR
• we can add a note somewhere that we are considering to split this pattern up in the future (e.g. under "Status")
• then let's merge the PR to main

Once that is done, we could do either of these:

• see how future conversations around this pattern go. if it turns out that it is confusing for readers in its current form then we can go back to the idea of splitting it up
• (or alternatively) if you wanted to start a draft about a dedicated pattern just for the release process, just to how that "feels like", that is of course also an option

How does that approach sound for you?

[dgrizzanti]

@spier made some updates based on the comments and added a line to Status about the potential future split

[spier]

LGTM

[spier]

Thanks for your contribution @dgrizzanti.
This is now available in the main branch and accessible via:
https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/release-process.md

I will try to figure out now what the markdown linter was complaining about :)