githubtraining / release-workflow

Course repo for Learning Lab course "Create a release based workflow".

Course: Create a release based workflow

This repository powers the Learning Lab course Create a release based workflow.

Every Learning Lab course is made up of:

• a course repository, and
• a template repository

The course repository is written in YAML and Markdown. The template repository could be written in any language that supports the learning objectives.

For more information on the goals of this course, check out the course-details.md.

Contribute

See something we could improve? Check out the contributing guide in the community contributors repository for more information on the types of contributions we ❤️ and instructions.

We ❤️ our community and take great care to ensure it is fun, safe and rewarding. Please review our Code of Conduct for community expectations and guidelines for reporting concerns.

License

All Learning Lab course repositories are licensed under CC-BY-4.0 (c) 2019 GitHub, Inc. The template repositories associated with each course may have different licenses.

When using the GitHub logos, be sure to follow the GitHub logo guidelines

release-workflow's Issues

Improve hotfix flow

During the hotfix, it feels like we're duplicating steps by approving a PR against the release branch and master. Let's instead:

1. Create the hotfix branch off of master.
2. Approve that PR.
3. Once merged, reverse merge master into the release branch.

Add .github release drafter file to template repository

This will need to be on master for the integration to work properly

Can't reverse merge to a protected branch

After shipping #50, the course becomes blocked because we can't reverse merge the change into a protected branch (release).

Why are users creating release at beginning of course?

Is this meant to show the "end in mind" first, and introduce releases, and then get into the workflow?

🤔 I can see it working both ways. What do you think @hectorsector @a-a-ron @hollenberry?

Todo: Check URLS

We need to go through happy path to make sure URLs within the course and the config are all functioning.

Feedback on course flow

@hectorsector here are some inputs I would love to discuss and have your thought on it 🙂

When creating a new release for the first time in the course flow:

• As an additional to the sentences for completing a release,would be good to include a note that the created releases can sometime be automated via a pipeline to be pushed to an artifact management application as part of an overall CI/CD strategy

When creating a new version:

• Do we want to emphasize on also providing an input for the tag?
• Should we also explain the differences between a tag and a release somewhere to indicate one is of git and the later is specific to GitHub?
• Error when no tag is provided

This is a little confusing for me, so maybe its just me:

• We've already created this branch, pull request, and suggested a fix. The suggested change will be merged into the release branch instead of into master. Later parts of the respond from the bot states the following Your fix is now on master! This ensures that any new code isn’t based on our bug, lets back port those changes to the branch with release v1.0 . See screen shot below

• Approve pull request step is hidden. Needs to be collapsed manually, is this intentionally done for trainees to look for the next steps?

vs

Overall:

• The flow is good and feels natural and captures the essence of a release based workflow with the right amount of activity instead of being too lenghty. ❤️
• With the release based workflow, are we highlighting how git-flow could be implemented via GitHub in combination with GitHubFlow? (apologies if this has already been discussed and I had missed that)
• We speak about the project board at that start but do not point back to it on how the issues are automatically moved within the columns when new issues are added and its progress are tracked. Is this intentional or did we not think about it? 🙂

Bug: Not able to accept suggested changes

Whenever I try to accept the suggested changes, I get an error about the branch being deleted:

Known problem: Project columns

There's a known bug having to do with project columns. I've opened an issue in learning-lab asking about permissions.

Once the permissions are figured out, we will need to uncomment the steps in the "before" step so that columns are created, and we'll need to add actions where Learning Lab moves issues and pull requests along within the project board.

Add information about what can be done with releases

As an additional to the sentences for completing a release,would be good to include a note that the created releases can sometime be automated via a pipeline to be pushed to an artifact management application as part of an overall CI/CD strategy

From #81

Step on finalizing the relase supposed to create a new release 1.0, not update the beta.

release-workflow/config.yml

Lines 230 to 243 in 21627c3

	#11 - The user approves the branch merge into master
	- title: Approve the release
	description: Approve the release branch in the pull request to finalize this release.
	event: pull_request_review.submitted
	link: '{{ repoURL }}/pull/7'
	actions:
	# We merge the pull request into the master branch
	- type: mergePullRequest
	# We create a new issue asking them to turn the draft release into a published release
	- type: createIssue
	title: Finalize the release
	# TODO: Step on finalizing the relase supposed to create a new release 1.0, not update the beta.
	body: 07.1_finalize-release.md
	action_id: finalIssue

Identify events and API endpoints

We need to identify the following in #9:

• events that trigger a step
• API endpoints for each step

Release draft not created by app

The https://github.com/toolmantim/release-drafter app should have created a draft release once installed, but alas, it did not.

Replace hard coded reference in config with something more flexible

Hard coded reference in the "create review" action in number 6 will cause errors if the user has extra issues or pull requests.

Happy path - notes and TODOs

I have gone through happy path, and I came up with a longish list of things to address. I think several of these are duplicates of open issues. I'm going to start tackling them now as I can, but I think I'll need to save several of the (flow related mostly) questions for a sync to more fully understand the intent.

Here's a list in case you're interested, I'll try to update this with pull requests as I go:

Responses

• Go through responses with Hemingway
• Add note in welcome issue = tour of releases page? What is being seen? When will we discuss it?
• LOVE the images added.
• Do we want to add a note about changing releases? What's possible to edit, what isn't? Who has permission to create or edit a release in a repository?
• Instructions for creating a project board
  • #2, we say "New project" but it should be "Create a project"
  • We don't tell users to select a template, or not select a template. Either way we should be explicit.
  • Then at final stage, click green "Create project"
• Comment (Columns)
  • More descriptive title?
  • Markdown problem
• Comment (Triaging issues)
  • Markdown problems
  • Consistent periods
  • "Under the label section of this issue, click "Projects" and then select your newly created project from the dropdown" doesn't make sense.
  • "but this time include automation" - what automation? Its there but not clear
• "Completion of this task resolves #2" - what? why? this issue says nothing about branching. Having a project board should resolve #2.
• We have new branches hanging around that aren't already part of pull requests. We should either have the pull requests already open, or we should address this early in the course.
• Issue named "Please fix this bug" has title of "Add a feature". Which is it? They should be consistent.
• The word "task" is all over the place
• Protected branches bit is difficult to understand because it's like, wait, it's already enabled? Am I supposed to do anything?
• Make sure we're consistent when asking users to delete branches after merging
• Planned ship date in template is random - the template should resolve an issue, and link to the project board.
• After opening a release PR, I got a comment, and then it said See my next comment below, but nothing is there. Probably should have pointed here: https://github.com/brianamarie/release-based-workflow/pull/8
• What does "Merging based on a "peer review session"!" mean? Is user supposed to review or merge?
• If you're interested in learning more about GitHub Apps, check out the Getting started with GitHub Apps course. Does this really have to do with this step? Not sure. We don't link to how to review a pull request when that's expected.
• Is "code freeze" the most important part? It seems to be if we use a more traditional Git flow... Not sure if that's the flow we're really preaching here or not
• "If you want to write better commit messages, Chris Beams wrote a great article." - is this necessary
• "Step 11: Finalize the release" - url in step 1 is broken
• Typo: For more information about suggest changes
• Step 13: or look into git cherry-pick for your local environment to carry changes over. - is that the best suggestion?

Flow

• Instructions - should we have them select automation? (YES) Why don't we have them just create a board that already is from a template?
  • Why don't we have them do a "done" yet? We should tell them the reason now
• Really think we could simplify automation into one step or something so that there's not so many focused on columns
• No release was created by app
• After applying suggestion, I wasn't able to merge without also reviewing (which isn't in instructions).
• End flow is very confusing. Bugfix goes straight into master, then what am I supposed to do?

Config

• After "Creating a release branch" is opened, close "Organizing a release"
• Links from main lab page not working (specifically step 13)
• Two activities are posted at once - Bugfix went straight into master?

There is no check for applied suggested changes

When the learner applies suggested changes, there is no check they've done this and, in fact, the next step is to check for a merge. The learner can't merge until they get an approval. We either need to:

• add a step that requests the learner approve the PR, and then the bot merges, or
• remove branch protections so the learner can merge their own PR without approval

release-workflow/config.yml

Lines 273 to 288 in e895b2a

	body: |
	```suggestion
	starCtx.fillStyle = "#000";
	```
	### :keyboard: Activity: Apply the suggestion
	# TODO: Bug: suggested changes can only be applied by assignees. Assign the learner automatically.
	1. Click **Apply suggestion**
	2. Enter a commit message
	3. Click **Commit changes**
	For more information about suggest changes, check out this [GitHub Help](https://help.github.com/articles/incorporating-feedback-in-your-pull-request) article.
	position: 5
	#13 - User resolves the bug, then merges the pull request.
	- title: Resolve and merge
	description: Resolve the bug, then merge the fix into the release branch
	event: pull_request.closed

Bug: Bot not doing anything

I'm not sure what I'm doing wrong, but the bot isn't doing anything after installation and merges into master.

To-Do

Happy path works, but these are the flow and technical issues that are still outstanding. There are gates that should be added in the config, and grabbing the branch name that a user creates, but those are separate from this list.

• Should user add the pull request/issue as step 3, for the bug issue created in step 2 ? Change name of project to Release 1.0? Then, the step of creating an issue just to add to the project board may instead be a comment in the bug fix issue, and that's the issue that would be added to the project board. 023a190
• Project board doesn't have columns. 4ea07b8
• Have bot delete branch after merge in step 8. d6cceb4
• User shouldn't close issue in step 2. Bot should do that for them, and the comment should only point them to the next issue. All important info should be in first OP or in a comment that's posted in "before" step. 3f0326f
• Maybe set branch protections again before bot opens its own PR so user doesn't just merge 0d64b55
• Delete outline 606ba07

Clarifying comments from config

(moved from #16)

@hectorsector I'm going through and fleshing out the config. I'm removing this comment, but want to paste it here so it doesn't get lost:

      # TODO: what if the bug is a hotfix that could also be applied into master?

I'm not sure what was meant by this original todo - if we want to cover hotfixes, should it come after the release PR is created? I'm a bit concerned that it could be confusing, but not if we do it right.

Another thing that's not addressed, is that the branch protection currently isn't set up to enable it with wildcards. Is that possible?

Draft Release bug(?)

I don't know if for this specific part of the course we want to test for the following things, but this is what I found in the following activity:

Activity: Create a release for the current codebase

• Tagged as v0.8, don't know if we want to enforce a tag name in this step
• Didn't select the draft release checkbox, app doesn't care

Repo creation is on githubschool instead of user's org

When joining the course the repo is being created on githubschool instead of the user's org.

Compared to the GitHub Pages course

Can't create suggested changes

release-workflow/config.yml

Lines 263 to 280 in 21627c3

	## Suggest a change in the new PR
	## This is kind of forced, so we don't need to keep it. I like the extra layer of interaction, though.
	# TODO: Fix this octokit bug
	- type: octokit
	method: pullRequests.createComment
	number: '%payload.pull_request.number%'
	path: game.js
	body: |
	```suggestion
	starCtx.fillStyle = "#000";
	```
	### :keyboard: Activity: Apply the suggestion
	1. Click **Apply suggestion**
	2. Enter a commit message
	3. Click **Commit changes**
	For more information about suggest changes, check out this [GitHub Help](https://help.github.com/articles/incorporating-feedback-in-your-pull-request) article.
	commit_id: '%actions.newPullRequest.data.pull_request.head.sha%'
	position: 5

request a review from the learner

release-workflow/config.yml

Lines 199 to 215 in 21627c3

	#9 - Bot creates a PR against release, learner approves, bot merges
	- title: Approve ships for an upcoming release
	description: Approve ships for an upcoming release
	event: pull_request_review.submitted
	link: '{{repoURL}}/pulls/8'
	actions:
	# TODO: request a review from the learner
	# TODO: adjust comment on PR #7 pointing to PR #8
	- type: mergePullRequest
	- type: octokit
	method: gitdata.deleteReference
	owner: '%payload.repository.owner.login%'
	repo: '%payload.repository.name%'
	ref: heads/green-colors
	- type: respond
	with: 06.2_github-app.md
	issue: 7

Point learner to last issue

We open the last issue but don't point the learner there. We should do that.

release-workflow/config.yml

Lines 325 to 334 in ed2a071

	- title: Release v1.0.1
	description: Create a release based on the most recent commit on the release branch
	event: release.published
	# link: '%actions.finalIssue.data.html_url%'
	actions:
	- type: createIssue
	title: Contratulations
	body: 15.1_congratulations.md
	- type: closeIssue
	issue: Create a patch release

Use a template for the PR so the learner doens't have to copy/paste

release-workflow/config.yml

Lines 152 to 156 in 21627c3

	- type: createIssue
	title: Create a release pull request
	# TODO: use a template for the PR so the learner doens't have to copy/paste
	body: 04.1_release-pr.md
	action_id: releaseIssue

Rewrite template history

Commits made by Hubbers should show as @githubteacher.

learner can't approve their own PR

bot will prob have to create the release PR for them if the approval is the action we want the user to learn

release-workflow/config.yml

Lines 217 to 228 in 21627c3

	#10 - The user assigns themselves to the pull request
	- title: Automation and assignment
	description: Install the GitHub app to help with release notes, then assign yourself to the pull request.
	event: pull_request.assigned
	link: '{{ repoURL }}/pull/7'
	actions:
	- type: respond
	with: 06.3_response.md
	# TODO: release drafter should be merged into this PR so the learner sees it
	# TODO: Bug: learner can't approve their own PR
	# Body: bot will prob have to create the release PR for them if the approval is the action we want the user to learn

Bug: Error'd Out

Got stopped dead in my tracks because LL comments weren't being placed on the correct issue / PR due to the issue identified here (#73). This probably isn't something that needs to be addressed, unless it occurs again with the correct number of issues and pull requests in the course.

release drafter config should be merged into this PR so the learner sees it

release-workflow/config.yml

Lines 217 to 225 in 21627c3

	#10 - The user assigns themselves to the pull request
	- title: Automation and assignment
	description: Install the GitHub app to help with release notes, then assign yourself to the pull request.
	event: pull_request.assigned
	link: '{{ repoURL }}/pull/7'
	actions:
	- type: respond
	with: 06.3_response.md
	# TODO: release drafter should be merged into this PR so the learner sees it

Blocking happy path: Lots of project board things

Happy path config currently has a thumbs up from Galileo bot, but in staging, gets blocked up by some "admin rights" things with the project boards.

I am pretty sure I have all of the correct fields, but I think I'm using action_id: incorrectly. @JasonEtco @githubtraining/learning-engineering Could you please help? (https://github.com/githubtraining/release-workflow/blob/master/config.yml)

Broken relative images

The image in the welcome issue is broken on real repos. Probably as a result of the relative reference to that image.

Reduce project-mangement steps

There are currently 3 project management steps, can we consolidate to 1? I envision that step would include creating an automated project board.

---

release-workflow/config.yml

Lines 9 to 14 in ba7c4b4

	before:
	# enable branch protection
	- type: updateBranchProtection
	# creating a welcome issue that will have the user's first instructions
	- type: createIssue
	title: Welcome

---

This issue was generated by todo based on a TODO comment in ba7c4b4 when #28 was merged. cc @githubtraining.

Rename project

The project board currently is named "Release 2.0", but it should be named "Release 1.0".

Find a template project

The outline is written, but before we dive to deep into it we should identify a template repository we'll use. This repo should organically lend itself to a release-based workflow.

Flow : Final bug fix order

I think the branch being merged first, and then backporting a bug, is a little too advanced for this course. It also can lead to so many unintended "unhappy paths", like if a user deletes a branch.

Edit: I also got stuck here, not sure why. 🤔 Not able to commit or apply the suggested changes.

Bug: Test for project board once

On Activity 2: Create a project board, if you create multiple project boards, you end up with something like this:

In this example, I created a board, deleted it, and created a new one

Project repo - Tasks to complete

• Add pointer to Alien Invasion
• Update README?
• Create a branch called green-colors
  • Create commit that changes text (and background -- bug) to green
• Create a branch called bug-fix
  • Apply suggested changes to the bug fix
• Add changelog file

adjust comment on PR #7 pointing to PR #8

release-workflow/config.yml

Lines 199 to 215 in 21627c3

	#9 - Bot creates a PR against release, learner approves, bot merges
	- title: Approve ships for an upcoming release
	description: Approve ships for an upcoming release
	event: pull_request_review.submitted
	link: '{{repoURL}}/pulls/8'
	actions:
	# TODO: request a review from the learner
	# TODO: adjust comment on PR #7 pointing to PR #8
	- type: mergePullRequest
	- type: octokit
	method: gitdata.deleteReference
	owner: '%payload.repository.owner.login%'
	repo: '%payload.repository.name%'
	ref: heads/green-colors
	- type: respond
	with: 06.2_github-app.md
	issue: 7

Add references and triggers to project board

Now there is a project board with three columns, and we have the user add something to "To Do", but we don't have them or the bot track the issues and PRS through the process. I think we should add some updates from the bot, so it feels like an automated board, and we can point the user back to the project board at some point(s) during the course.

rewrite 08.2 so that it shows we will merge into the release branch next

release-workflow/config.yml

Lines 289 to 294 in 30d5026

	starCtx.fillStyle = "#000";
	```
	### :keyboard: Activity: Apply the suggestion
	1. Click **Apply suggestion**
	2. Enter a commit message
	3. Click **Commit changes**

---

This issue was generated by todo based on a TODO comment in 30d5026 when #50 was merged. cc @githubtraining.

Odd: PR template was confusing

The PR template being in the project when creating the first PR against the release-v10 branch just seemed out of place, especially without any context:

Question: Branch Creation

For Activity: Update the README.md do we want the user to create the new branch off of master or the release-v1.0 branch?

Release page link not working

The Release page link in the first issue doesn't link to the releases section of the repo.

Close stale issues

A number of issues in the repo remain open after the step is completed. Issues should be closed that no longer contain actionable steps.

Change merging of release branch step

Currently, users are approving a pull request that merges the release branch into master. After chatting with @hectorsector, this doesn't really mimc a realistic flow. Realistically, there are many smaller pull requests merged into the release branch.

I propose that we:

• Open the pull request at the same time
• Open an additional pull request from some branch into v1.0 or whatever the release branch is named
• Instruct users to approve the additional PR

After they do that, we'll merge the additional PR and point them back to the release PR, showing them that it has changes from multiple smaller PRs. At that point, we could:

• create a release from the branch, then merge (or not merge?) (not sure why we'd do this)
• remove the protected branch status and have the user merge, then continue as normal

Can we check for a user's app installations?

Also, double checking, can we see if a user has installed a specific app on their repository? I've written the config to look for an issue closing, based on the Introduction to GitHub Apps course, but if there's a way to have an event that they've installed, or even a gate, that would be 👍. cc @hectorsector @hollenberry @JasonEtco

Flow: We create release-v1.0 instead?

Right now, we're asking the user to create the release-v1.0 branch. This is all fine and well, but I worry that we will get a lot of users who name it something slightly different, and have problems throughout the course.

• What are we teaching by having the user create the branch instead of us?
• Are there other ways to teach that?
• What are we risking by having the user create the branch?

Improve instructions for tags and releases

Do we want to emphasize on also providing an input for the tag?
Should we also explain the differences between a tag and a release somewhere to indicate one is of git and the later is specific to GitHub?
Error when no tag is provided

From #81

Bug: suggested changes can only be applied by assignees. Assign the learner auto...

release-workflow/config.yml

Lines 278 to 283 in 8ea308d

	# TODO: Bug: suggested changes can only be applied by assignees. Assign the learner automatically.
	1. Click **Apply suggestion**
	2. Enter a commit message
	3. Click **Commit changes**
	For more information about suggest changes, check out this [GitHub Help](https://help.github.com/articles/incorporating-feedback-in-your-pull-request) article.
	position: 5

---

This issue was generated by todo based on a TODO comment in 8ea308d when #40 was merged. cc @githubtraining.

Bug: Bot thinks that automated cards are the user's cards

Now, the user is creating an automated kanban board. Then, GitHub adds cards.

Subsequently, our bot finds those cards, and it triggers the next step as if the user had done it. 🤔

Find a probot app to create a changelog

Step 9 in this course requires the user to install a Probot app that writes a changelog, but we haven't found this app. If one doesn't exist, we need to find a simple replacement that makes sense in a release-based workflow.

Suggested by @JasonEtco: https://github.com/toolmantim/release-drafter