Tags and Releases: create tags and releases page for github games repo#45
Tags and Releases: create tags and releases page for github games repo#45brianamarie merged 4 commits intomasterfrom
Conversation
There was a problem hiding this comment.
@brianamarie and @hollenberry thank you for kicking this off. It will be so nice to finally see this ✔️ on the to-do list - I made a few notes below.
|
|
||
| ### Tags | ||
|
|
||
| A tag is a pointer that points to a specific commit. Unlike commits, tags are _not_ immutable. They can be moved and changed. Before we get into Releases, let's practice a bit with tags. |
There was a problem hiding this comment.
Since we haven't really talked about tags yet, I think we could remove "Before we get into Releases," here.
|
|
||
| To see all tags, type `git tag --list`. | ||
|
|
||
| Another caveat with tags is that they are not automatically pushed up with commits. To push tags, type `git push <remote> --tags`. |
There was a problem hiding this comment.
You don't technically need the remote here. You can just do git push --tags. You can also set this as a default with configs using git config push.followTags true which will automatically push tags when their associated commits will be pushed. See more.
|
|
||
| A tag is a pointer that points to a specific commit. Unlike commits, tags are _not_ immutable. They can be moved and changed. Before we get into Releases, let's practice a bit with tags. | ||
|
|
||
| When creating a tag from the command line, you can make a "lightweight" or an "annotated" tag. The following example creates an annotated tag with the `-a` flag, names the tag `v1.0`, and connects it to whichever commit SHA is included. |
There was a problem hiding this comment.
Let's remove "lightweight" here since we aren't covering them and don't recommend them 😉
|
|
||
| ### Releases | ||
|
|
||
| Releases are similar to tags, because they point to a specific commit and can be named like any other tag. However, releases can also include attached binaries. This means you can upload and store the compiled program for others to download, and have that compiled version be attached to the exact source code that composes it. We recommend using GitHub Releases in place of tags; a tag will still be created, but it will have a GitHub linked history that cannot be changed. |
There was a problem hiding this comment.
It might also be important to note that Releases are a GitHub only thing where tags are both Git and GitHub. I usually say something like "Tags can be created locally with Git, or on GitHub. However, releases are a GitHub feature that allow you to add an executable to the tag for easier access by visitors who just want to download and install your software."
We recommend using GitHub Releases in place of tags; a tag will still be created, but it will have a GitHub linked history that cannot be changed.
I may be reading this wrong, but this is not technically true. You can do the following:
- Create a tag locally and push it to GitHub
- Add a release binary to the tag on GitHub
- Delete the tag locally and recreate a tag with the same name pointing to a different commit
- Use
push --forceto overwrite the tag on GitHub with the new commit ID.
From what I can see, the earlier commit ID that v1.0 pointed to is not stored.
| 1. On GitHub, navigate to the main page of the repository. | ||
| 1. Under your repository name, click Releases. | ||
| 1. Click Draft a new release. | ||
| 1. Type a version number for your release. Versions are based on Git tags. We recommend naming tags that fit within semantic versioning. |
There was a problem hiding this comment.
Versions are based on Git tags. We recommend naming tags that fit within semantic versioning.
Type a name for the tag. We recommend you use semantic versioning.
| 1. Under your repository name, click Releases. | ||
| 1. Click Draft a new release. | ||
| 1. Type a version number for your release. Versions are based on Git tags. We recommend naming tags that fit within semantic versioning. | ||
| 1. Select a branch that contains the project you want to release. Usually, you'll want to release against your master branch, unless you're releasing beta software. |
There was a problem hiding this comment.
You can also select a recent commit by clicking the drop down and choosing recent commits.
|
Sorry about leaving you off @brianamarie --- that's what I get for not looking at the discussion page before starting my review |
|
@crichID ✨ Updates made. Does this look better to 🚢 now? |
|
@brianamarie I think this looks great. Thank you for finally adding this section to the manual, it has been a long time in the works. |
3 participants
This pull request resolves #15 by adding a page where users will add a release to their github-games repository.
@githubtraining/trainers This still needs some hefty review, but it's a start! 👍