Documentation review - The Git-based process you need for mainframe Development

[M-DLB]

Hello dear Community!

@dennis-behm, @ijmitch, @lauren-li and myself worked together on a document describing a Git-based process for managing the lifecycle of mainframe source files. It outlines the preferred approach to benefit from Git and IBM Dependency Based Build when developing mainframe applications, while maintaining essential outcomes associated with traditional workflows. The overall development process is depicted in this guide, discussing the role of the different branches, how developers efficiently use the branching model and how to implement such a workflow in your environment.

The document is currently accessible at this location.

The current version is still a draft version that we are polishing, and it shall be officially released when ready.
We're looking for feedback! Please share your thoughts in this discussion, and feel free to propose your changes through Pull Requests!

[ijmitch]

Kicking off the discussion, what do you think about the whole aim to propose a single recommended workflow?

And for that workflow to have strong similarities to workflows commonly employed for non-mainframe development - or put another way, with the aim to minimize or eliminate 'mainframe unique' variations?

As we recognise early on in the material, the core of the workflow is essentially the one described by Microsoft on their Azure Devops pages - but we then describe the means by which DBB can be used to support incremental builds within that branch strategy and workflow.

[lauren-li]

To provide some more context on this question, in September 2022, the IBM Z DevOps Acceleration Team published documentation of a "Release-based" branching model, which was based heavily on Vincent Dreissen's git-flow approach (which is also used by some non-mainframe development teams).

@ijmitch, @M-DLB, and @dennis-behm, perhaps it would be helpful to consider a pros/cons comparison of the "Git-based process you need" and the "Release-based" branching models (or if one model might be more suited than the other in certain use cases/circumstances)?

[ijmitch]

Hi @lauren-li ... "Release-based" document is this PDF.

My personal approach here is that, as with all the discussions about these workflows and branching schemes, the descriptions of the named ones are starting points - you might use one as-is or simply as a basis and add your own 'twiddles'.

There's not all that much change from the 2022 'release-based' workflow, but an aim I had was to remove as many apparent 'mainframe-unique' words in the vocabulary and see how workflows described elsewhere would achieve the same outcomes.

So, as a prime example, there's no prod or production branch in our 2023 document. In the 2022 structure, the HEAD of prod branch was assumed to be the place to go to see what was in production. But since that branch only ever saw commits from points in the commit history of development that were declared to be releases, it actually has nothing to add to the outcomes except something uniquely 'mainframe' and unjustified.

(If we had started using git for this before now, then we'd simply be evolving the 2022 document into the 2023 one with complete transparency of the reasons - that's why I love that we're all here now!)

[lauren-li]

Thanks @ijmitch for including the link to the "Release-based" branching model document I was referencing in my earlier comment! (In linking Dreissen's approach, I mistakenly thought I had linked ours there, as well. 😅 Apologies for leaving it out!)

I believe some non-mainframe development teams use a version of the prod/production branch the way we described it in the 2022 "Release-based" document (although they might call it something more like main). At least, on a previous (non-mainframe) development team, I did something similar. However the team has since evolved into using something much closer to what's being proposed in the "Git-based process you need" draft.

Some reasons for the switch included a simplification of the branching structure, and a preference for being able to see the current work for the next release in the default branch. A important enabler of this approach for them are short-lived (feature) branches that are well-tested ("early and often") via a CI/CD pipeline and code review before being merged into main, which should always be in a deployable state. Together, this helps encourage the short, iterative development cycles that are used in the Agile/DevOps ways of working. (I believe these points all have at least some coverage in the document already.) Just wanted to share the team's perspective (although, of course other teams may be different), having tried versions of both the "Release-based" and "Git-based process you need" approaches.

[ijmitch]

Oh, I'm sure that it isn't just mainframe teams who are tempted to add their own variations! And I'm not saying that variations shouldn't be allowed, but we ought to recommend the most correct, most common/recognizable one as the true core.

It's good to hear the motivations for change - reviewing how it's working on a team-by-team basis is another thing to be encouraged.

[M-DLB]

Good to hear that kind of feedback indeed! GitFlow seems to be a bit of overkill, and to me it feels risky to use as it provides the capability to package from any branch and potentially deploy that package up to production through the CI/CD pipeline. Having the main branch as the mandatory integration gate for packaging/deploy to production is a safer approach to me.
The release branches, used for maintenance purpose, are there in case you want to check the version of the source code that is associated with a deployed version (and to develop hotfixes of course).

[M-DLB]

A Pull Request has been opened to also track the comments on the document itself, which is easier than the discussion thread;. Feel free to comment also in the Pull Request.

[ijmitch]

Great, now that we have the PR, we get the benefit of inline commenting on the content - see the 'conversation' tab of #415 for examples.

[ijmitch]

We are not currently mentioning anything about cases were there are problems in production. The 'backout' concept is prevalent with the current tools whereas we are advocating the 'hot-fix' approach which is quite a different mind-set.

[ijmitch]

Comment at the point where this should be... https://github.com/IBM/dbb-zappbuild/pull/415/files#r1342401951

But maybe we do need it mentioned in the Introduction too.

[M-DLB]

It's probably not clear in the document, but I think we can consider that "backout" approach is at the loadmodule level (i.e., things that are deployed) while "go-forward" approach is at the source-level.
I think this is not contradictory: to solve a problem in production, you are tempted to rollback to a previous version for quick resolution. But it doesn't mean you also implement your fix on the rolled-out version of your source (i.e., the previous version of the application), you would implement your fix on the source that represent the version that has the problem in production (so it's still "go-forward" mode).

[ijmitch]

Agree @M-DLB, there's a decoupling between the state of the production system and the state of the SCM via the build system which is more explicit here (less of a monolith, dare I say!).

Definitely the rollback of the production system to the prior state when that's justified by the type of problem should be no challenge at all - and the alignment of that 'old' state of the production system to a known build and thus a known point in the history of the code base is similarly well understood.

I think we're agreeing that it just needs to be expanded a bit in the content.

[dennis-behm]

Thank you to everyone who has reviewed and provided feedback on the The Git-based process you need for mainframe development. I hope you enjoyed reading it and it provided you with some food for thought.

We are happy to announce, that we have published last week the final documentation of the Git branching model and developer workflows, that now can be found at the solution page of the IBM DevOps Acceleration Program at: https://ibm.github.io/z-devops-acceleration-program/docs/branching-models/

We appreciate your feedback and take any Q&A - such as questions and comments about the strategy, or any particular section, paragraphs which are unclear and require more explanation. Please use the feedback form of the GitHub pages, or open an issue at the git repository at https://github.com/ibm/z-devops-acceleration-program/

The referenced branch and any remaining open pull requests were closed.