GovTool GitHub workflow proposal

[placek]

GovTool Project GitHub Workflow Guide

This guide outlines the structured workflow for the GovTool project, designed to optimize collaboration among developers, QA (Quality Assurance), and product owners across multiple environments. Our objective is to ensure a seamless, transparent, and efficient process from development to deployment.

Environments

The project utilizes four key environments for deployment:

• dev: A development environment for developers to test and refine their work.
• test: An environment for the QA team to verify the developers' work.
• staging: A pre-production environment for product owners to review and approve work before it moves to production.
• beta: The production environment, maintained with specific semantic versioning.

Branch Structure

• main: The production branch, updated to deploy to the beta environment.
• preprod: A branch for integrating verified development work, serving as the base for feature branches.

Workflow Steps

1. Branching

• Developers create new branches for each ticket, branching off from preprod or any epic-related subbranch of preprod.
• Branch naming should reflect the ticket being worked on for clarity and tracking.

2. Committing

• Each commit should correspond to an atomic change, including a title, ticket number, and a comprehensive explanation of the change.

3. Pull Requests (PRs)

• Once development is complete, the branch is submitted as a PR, tagged as waiting for code review.
• Code reviews must address all comments and resolve them as necessary.
• After code review approval, the QA team is notified to deploy the branch to the test environment for testing.

4. QA Approval and Merging

• Following QA approval, the PR is merged into its origin branch (preprod or the specific epic branch).
• Automatic deployment to staging is triggered when preprod is updated.

5. Deployment to Production

• Updating the main branch triggers automatic deployment to the beta environment.

Best Practices

• Regularly rebase feature branches with it's origin to minimize merge conflicts.
• Ensure thorough testing in each environment to prevent regressions.

Releases

Releases are a critical part of the workflow, ensuring that new features, fixes, and updates are systematically introduced to the production environment. The process involves creating a dedicated release branch, preparing it for the release, and merging it into the main branch.

1. Release Branch Creation

• For each release, create a dedicated branch off preprod. This branch is used for final preparations before a release, such as documentation updates.
• Name the release branch in a way that reflects the release version and purpose for easy identification.

2. Preparing the Release

• Documentation Adjustments: On the release branch, make any necessary adjustments, including updating the changelog and any other documentation relevant to the new release. This ensures that all changes, features, and bug fixes are accurately documented.
• Final Testing: Conduct thorough testing on the release branch to ensure stability and that all features work as expected. This is the final check before the changes are moved to production.

3. Merging into Main

• Once the release branch is fully prepared and tested, merge (do not rebase) it into main. Merging helps preserve the history of changes and ensures a clear pathway from pre-production to production.
• The merge into main triggers the deployment process to the beta environment, marking the official release of the new version.

---

This guide is intended to evolve as the project grows and adapts, ensuring the workflow remains aligned with the project's goals and the team's needs.

[placek]

I've suggested keeping the preprod branch flat with no merge commits, but I think it will be counter productive since in scenario where we want to create a realase candidate branch we also want to cherry pick the actual features, and that can be easily done with git cherry-pick -m … method.

[kickloop]

@Ryun1 Please take a look. Seems reasonable. Let's just make sure that it fits across teams

[Ryun1]

@placek
This is a very comprehensive write up, thank you for taking the time to want to improve how we work 💪

I have two questions;

• How well would this work for when govtool, is a monorepository? how would a separate team working inside same repo (although on different code) play into this?
• What stake holders would be needed to organise a release? im thinking if this would add significant overhead

[placek]

Hey @Ryun1 ,

Regarding your question on how our proposed changes would work within a monorepo setup for GovTool:

We advocate for working on feature branches and utilizing corresponding pull requests, where each branch is then merged back into the origin upstream branch upon completion. The key practice here is to ensure that each feature branch is rebased onto the original branch just before merging. This step guarantees that the feature branch contains only the implementation of the feature in question.

In my opinion to fully utilise this approach only the QA members of each team should be able to (and responsible for) merging PRs, since this is a reasonable assurance of the proper implementation of the feature.

This system of delivering features will be accessible to everyone working within the monorepository. It's goal is to make each newly introduced feature an independent piece of the application making it separated and as isolated as possible from other pieces. Therefore the delivery of many such features from many different teams should not be disturbed by conflicts we have already in our current setup.

The merge commits will clearly indicate the code that implements the functionality delivered for a specific task. This method promotes clear organization and minimizes potential conflicts, ensuring that different teams can work simultaneously on separate pieces of code without hindering each other's progress.

[placek]

In response to your question about the stakeholders involved and the potential overhead in organising a release, our process is designed to be both efficient and manageable. The release of a new version involves three main steps:

1. Branching a Release Candidate from the Main Branch: This step is straightforward. We create a release candidate branch directly from the main branch, which serves as the basis for the upcoming release.

2. Cherry-Picking Merge Commits onto a Preprod Branch: This step involves selecting and applying merge commits that introduced new features into a preprod branch. It requires familiarity with Git or it's wrapper, but we've streamlined the process to ensure it's manageable. This task is typically handled by developers. Until the pull request (PR) is merged, QA can deploy the release candidate branch to a testing environment, allowing for thorough testing and validation.

3. Creating a Pull Request to the Main Branch: The final step is also straightforward, involving merely the action of clicking to merge a PR. I plan to automate the tagging and creation of the release at this stage, which will further reduce manual effort and minimize the chance for errors.

These steps are designed with simplicity and automation in mind to ensure that the process is not burdensome for any team member. By delegating specific responsibilities to developers and QA, and automating final steps, we aim to streamline the release process without adding significant overhead. This approach allows us to maintain agility and ensure that releases are managed efficiently, with clear roles and minimal manual intervention.

[placek]

In addition to that from my personal experience, I designed this model basing it on the existing model well tested on the huge monorepo I recently was working with. The repo I'm talking about is seven years old and has 70k+ commits with about 10k PRs closed. There were several, independent teams working on it, so I think that's a good reference.

[Ryun1]

Thanks again for this very very good write up @placek

This sounds great, lets do it!

[kickloop]

As already pointed out above, the proposed process is definitely interesting but it create a potential for issues and problems once you try to distribute it to more than one team, especially if teams structure is not the same. Ryan asked some pretty good and obvious questions but then you assumed that only teams, and only well structured teams will contribute to the repository, which is definitely not the case.

You have to remember that we are only putting some ground work for the whole Cardano community and we are aiming to fully open-source our repositories. Please do not assume that contribution to this repo will only come from well organised and structured teams, with PM's, developers, QA engineers and DevOps engineers. In most cases, the contributions will come from a single developer! Not always seasoned developer. "someone" still need to check PR, do code review, and then pass to "some" QA engineer. In our current setup I strongly doubt that you first will pickup to do a Code Review for a PR where some random person want to change something on for example a feature or on a library which is not in your scope or related to your delivery :) Well, we need a solution and a process for that as well.:)

On top of that, currently we are dealing with monorepo, and soon there will be shared libs, packages and dependencies for each team to contribute or make necessary changes to complete their tasks. What is the process when, for example WeDeliver developer change a React Component which you use as well?

When you take all this into consideration, then your proposal, still pretty good, becomes much much harder to implement. Not that it is impossible but just it will create huge potential for issues and problems.

My proposal at this moment is that we stick to minimal agreed process we have, and practice a bit across teams. You guys are here the longest and for you, 100% the new process you proposed is better. But not all builders are on your level and we simply have to be careful and wait until we make such drastic changes prone to issues.

My suggestion is that you try to think about all this from much broader perspective that your own. We are more than willing to share all the information with you and we truly welcome not only your contribution to the project but also your willingness to make everything better. Let's then put you into right perspective, and let's figure this out together!

P.S. Do not consider this comment as end of discussion :) Let's keep polishing your proposal and make it work, but considering much broader big picture than perhaps the one you have in mind.

[placek]

As already pointed out above, the proposed process is definitely interesting but it create a potential for issues and problems once you try to distribute it to more than one team, especially if teams structure is not the same. Ryan asked some pretty good and obvious questions but then you assumed that only teams, and only well structured teams will contribute to the repository, which is definitely not the case.
You have to remember that we are only putting some ground work for the whole Cardano community and we are aiming to fully open-source our repositories. Please do not assume that contribution to this repo will only come from well organised and structured teams, with PM's, developers, QA engineers and DevOps engineers. In most cases, the contributions will come from a single developer! Not always seasoned developer.

I have never assumed that only a competent, well-structured team will contribute
to this project. I understand the term "open-source."

In open-source solutions, there is, however, the group of code owners
responsible for delivering contributed work from the community to the end
product stage. My proposal aims to make the work of code owners easy,
straightforward, and free from any burdensome chores. This proposal addresses
this by making delivery simpler (by reducing the number of branches involved in
the process of delivery), PR-driven (by using a single preprod branch as a base
for any forking), and more focused on features (by reviewing and testing
features on target feature branches before they end up on staging, i.e., being
considered as done).

This solution also reduces the risks of potential mistakes that can be made
while transitioning between our main branches. Now we are cherry-picking pieces
of work to form a PR before delivering it to test, staging, beta which makes us
three points where things can potentially go wrong. I reduced it to potentialy
one such point - on transition to beta.

I hope that makes clear what is the goal of that proposal.

"someone" still need to check PR, do code review, and then pass to "some" QA engineer. In our current setup I strongly doubt that you first will pickup to do a Code Review for a PR where some random person want to change something on for example a feature or on a library which is not in your scope or related to your delivery :) Well, we need a solution and a process for that as well.:)

Of course, someone has to verify that the PR made by some random person is not
introducing any potential bugs, risks, or even exploits. I believe that there
has to be (and I hope there will be) some automation involved to make that
verification as strict as possible. This has to be done right before the code
owners pick up the PR to make code review and QA testing.

In my proposal, the point where the code review and the following QA testing are
performed is on a feature branch, just after the PR is delivered and checked
against automatic tests, before it's merged. Only when all checks are green and
the code reviewer and QA tester leave their approvals should the PR be unblocked
for merging.

After it's merged, there should also be an automated smoke test performed if we
do not want to involve a QA tester.

On top of that, currently we are dealing with monorepo, and soon there will be
shared libs, packages and dependencies for each team to contribute or make
necessary changes to complete their tasks. What is the process when, for
example WeDeliver developer change a React Component which you use as well?

As you've pointed out, the process should be the same for the team member from
any of the teams involved as for the random open-source contributor.

When you take all this into consideration, then your proposal, still pretty good, becomes much much harder to implement. Not that it is impossible but just it will create huge potential for issues and problems.

I think I need to ask you for an explanation here. I don't quite understand what
in the simpler and more transparent process can be harder. Less complexity in
the structure leads to simplicity in implementation.

Furthermore, as I see, the GovTool is the only repository with such complexity
involved in the scope of the IntersectMBO organization. Other repositories have
only one main branch, and they are already open-source. How can their
implementation "create a huge potential for issues and problems"? Are they
having any problems with their processes? If not, maybe we should incorporate
their ways of delivering instead of reinventing the wheel. Of course, I
understand that those other projects like cardano-node are rather tools than
apps, but I've taken that into consideration while designing my proposal.

My proposal at this moment is that we stick to minimal agreed process we have, and practice a bit across teams.

In my humble opinion, this process is not minimal; it's bloated. That's why I
published the proposal in the first place.

You guys are here the longest and for you, 100% the new process you proposed is better. But not all builders are on your level and we simply have to be careful and wait until we make such drastic changes prone to issues.

No matter the level of competence of any member of any team involved, this
change is not huge at all, easy to comprehend, easy to implement, fewer steps in
the delivery process, fewer people involved in that process, fewer blocked
issues on the board, and shorter delivery of features - everyone can only
benefit from that.

My suggestion is that you try to think about all this from much broader perspective that your own.

I am. In fact, I am thinking not only about my team or any other team that will
join us - I am trying to think of open-source contributors, code owners, and
end-users as well.

We are more than willing to share all the information with you and we truly welcome not only your contribution to the project but also your willingness to make everything better. Let's then put you into right perspective, and let's figure this out together!

I hope we will. :)

[placek]

Just to be clear:

I don't want to torpedo the current process. I just see some risks and try to address them to make our work simpler and more productive with less frustration.

[placek]

GovTool GitHub workflow proposal.pdf
This is a case study presenting differences between current workflow and the proposed one.

[Ryun1]

Thank you for raising @placek

Lets do it 🚀