GitHub Procedures: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(98 intermediate revisions by the same user not shown)
Line 2: Line 2:


* [[GitHub#Procedures|GitHub]]
* [[GitHub#Procedures|GitHub]]
=<tt>gh</tt> CLI=
{{Internal|gh#Overview|gh}}


=Making a Public Release=
=Making a Public Release=
Line 9: Line 12:
This is the procedure to make a "public release" for a GitHub-hosted project. This type of releases are accessible via the GitHub project page -> "releases" tab. The release procedure assumes that the release tag was already applied to the repository, either manually or via [[nort]]. At the time of the writing, [[nort]] is being extended to automate this procedure.
This is the procedure to make a "public release" for a GitHub-hosted project. This type of releases are accessible via the GitHub project page -> "releases" tab. The release procedure assumes that the release tag was already applied to the repository, either manually or via [[nort]]. At the time of the writing, [[nort]] is being extended to automate this procedure.


==Procedure==


GitHub Project Home -> "releases" tab -> "Draft a new release"


Draft a new release
Copy and paste the release tag from the local release procedure output or from git tag output. The format is similar to "[project-name-]release-4.2.2".


Copy and paste the release tag from the local release procedure output.
Upon pasting it into the release input box, the site should recognize it as "Existing tag".


Tag: release-1.0.3
Release title: 4.2.2


The logic should recognize it as "Existing tag"
Describe the release:


Release title: 1.0.3
Specify Introduced features and defect fixes. This will be part of the release history. Projects maintain notes to be consolidated into the release announcement in <tt>./doc/release-notes.md</tt>. Copy and edit the content from there.


Describe the release: Introduced features, bug fixes. This will be part of the release history. Projects maintain notes to be consolidated into the release announcement in <tt>./doc/release-notes.txt</tt>.
Attached files:
* If is an installable release, attach binaries: "Attach binaries by dropping them or selecting them."
* If it is a library release, don't attach anything, as the libraries can be recreated from the tagged source tree, and in the future, we'll publish to a public Maven repository.


Clean <tt>./doc/release-notes.txt</tt> and commit.
"Publish release"
 
Clean <tt>./doc/release-notes.md</tt> and commit.


<pre>
<pre>
cat /dev/null > ./doc/release-notes.txt
cat /dev/null > ./doc/release-notes.md
git add ./doc/release-notes.txt
git add ./doc/release-notes.md
git commit -m "cleaned ./doc/release-notes.txt post-release"
git commit -m "cleaned ./doc/release-notes.md post-release"
git push
git push
</pre>
</pre>


If is an installable release, attach binaries: "Attach binaries by dropping them or selecting them."
=Link to a Specific Line=
 
Use #L<start>-L<end>
 
https://github.com/moby/moby/blob/master/oci/defaults.go#L14-L30
 
=Issue Queries=
 
{{External|https://help.github.com/articles/searching-issues-and-pull-requests/}}
 
is:issue is:open author:ovidiuf
 
=Authentication=
==Create a Personal Access Token for Command Line==
 
{{External|[https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line Creating a personal access token for the command line]}}
 
This procedure describes creation of [[GitHub_Concepts#Personal_Access_Token|personal access tokens]]:
 
Profile-photo icon -> Drop Down -> Settings -> Developer settings -> Personal Access Tokens -> Generate a new token.
 
Token description:
 
OAuth scopes: To use your token to access repositories from the command line, select repo.
 
Make sure to copy your new personal access token now. You won’t be able to see it again!
 
Scopes:
 
[[File:Minimal_GitHub_PAT_Permissions.png]]
 
Other PAT Operations:
* [[#Authenticate_with_a_Personal_Access_Token|Login with PAT]]
* [[#Authentication_Status|Login status]]
 
==GitHub Authentication for AWS CodePipeline==
 
{{Internal|GitHub Authentication for AWS CodePipeline|GitHub Authentication for AWS CodePipeline}}
 
==Connecting with SSH==
{{External|https://docs.github.com/en/enterprise-server@3.6/authentication/connecting-to-github-with-ssh}}
 
Use your current SSH key from <code>~/.ssh</code>. If you don't have one, this is how you generate one: {{Internal|Ssh_Configure_Public/Private_Key_Authentication#Create_the_OpenSSH_Private.2FPublic_Key_Pair|Create the OpenSSH Private/Public Key Pair}}
 
Add the public key to the GitHub account: User Dropdown → Settings → SSH and GPG keys → New SSH key → Title, Key.
 
Test:
 
<syntaxhighlight lang='bash'>
ssh -T git@github.com
 
Hi ovidiu! You've successfully authenticated, but GitHub does not provide shell access.
</syntaxhighlight>
 
=Pull Request Procedures=
 
{{External|https://help.github.com/en/articles/searching-issues-and-pull-requests}}
 
==Search Pull Requests==
 
===Open Pull Requests===
 
is:pr is:open
 
===Based on the Branch They Are Merging Into===
 
base: ''BASE_BRANCH''
 
===By Author===
 
author: ''USERNAME''
 
==Merge an Approved Pull Request==
 
{{External|https://help.github.com/en/articles/merging-a-pull-request}}
{{External|https://help.github.com/en/articles/about-pull-request-merges#squash-and-merge-your-pull-request-commits}}
 
There are three options:
* <span id='Create_a_Merge_Commit'></span>'''Create a merge commit''': all commits from the [[Git_Concepts#Head_Branch|head branch]] will be added to the  [[Git_Concepts#Base_Branch|base branch]] with a [[Git_Concepts#Merge_Commit|merge commit]]. The commits on the head branch are preserved in the repository. The merge is performed using the [[Git_merge#--no-ff|--no-ff]] option.
* '''Squash and merge''': if the [[Git_Concepts#Head_Branch|head branch]] contains multiple commits, they are squashed into single one. Then the resulting commit is merged into the [[Git_Concepts#Base_Branch|base branch]] using the fast forward option. <font color=darkgray>What if in the mean time, new work also occurred on the base branch? Most likely, a [[Git_Concepts#Merge_Commit|merge commit]] will be created. Verify that.</font> This option might be useful if you try create a more streamlined Git history in your repository. Work-in-progress commits are helpful when working on a feature branch, but they aren’t necessarily important to retain in the Git history. If you squash these commits into one commit while merging to the default branch, you can retain the original changes with a clear Git history. Of course, squashing can be done prior to the pull request, based on logical considerations and commit boundaries.
* '''Rebase and merge''' - all commits from the [[Git_Concepts#Head_Branch|head branch]] are added on the base branch individually without a [[Git_Concepts#Merge_Commit|merge commit]].
==Insert a Suggestion within a Pull Request==
 
Click on the Blue + → "Insert a Suggestion" icon:
 
[[File:InsertaSuggestion.png]]


If it is a library release, select the JAR and the source JAR from the project's target directory and attach them.
==Change the Base Branch of a Pull Request==
{{External|https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request}}
==Make a Pull Request from a Forked Repository==
{{Internal|Git_Forked_Repository_Operations#Overview|Forked Repository Operations}}


Publish release.
=Create a Repository=
* Immediately after creating the repository with the UI, clone it locally.
* Create and push the "develop" branch.
<font size=-1>
git checkout -b develop
# local change
git commit -m "'develop' init"
git push --set-upstream origin develop
</font>
* Settings → General
** Pull Requests
*** Enable "Automatically delete head branches"
*** Disable "Allow merge commits"
*** Leave "Allow squash merging" and "Allow rebase merging"
* Settings → Branches → Default branch → Switch default branch to another branch (⇄ icon) → "develop"
* Settings → Branches → Branch protection rules → Add Rule. For branch name pattern: "main", "develop"
** Require pull request reviews before merging: Required approving reviewers 2,
** Do not check "Dismiss stale pull request approvals when new commits are pushed", it's a pain.
** "Require review from Code Owners" if Code Owners is setup for repository.
** <span id='Prevent_PR_Merging_on_Failed_Pipelines'></span>'''Prevent PR Merging on Failed Pipelines''' Enable "Require status checks to pass before merging". For more details see [[GitHub_Concepts#Requiring_Status_Checks_Before_Merging|Require status checks to pass before merging]].
** "Require conversation resolution before merging"
** Do not check "Do not allow bypassing the above settings". This will allow admins to merge without an approval. At the same time, it will allow the admins to push from command line on the branch, which may be a problem.
** Do not check "Allow force pushes", this will prevent admins to accidentally force push from command line.
** Create
* Settings → Notifications → Address: space separate list → Use the OD group address. Setup notifications.
* Settings → Collaborators & teams → Add a team with "Write" permissions.

Latest revision as of 21:37, 19 July 2024

Internal

gh CLI

gh

Making a Public Release

Overview

This is the procedure to make a "public release" for a GitHub-hosted project. This type of releases are accessible via the GitHub project page -> "releases" tab. The release procedure assumes that the release tag was already applied to the repository, either manually or via nort. At the time of the writing, nort is being extended to automate this procedure.

Procedure

GitHub Project Home -> "releases" tab -> "Draft a new release"

Copy and paste the release tag from the local release procedure output or from git tag output. The format is similar to "[project-name-]release-4.2.2".

Upon pasting it into the release input box, the site should recognize it as "Existing tag".

Release title: 4.2.2

Describe the release:

Specify Introduced features and defect fixes. This will be part of the release history. Projects maintain notes to be consolidated into the release announcement in ./doc/release-notes.md. Copy and edit the content from there.

Attached files:

  • If is an installable release, attach binaries: "Attach binaries by dropping them or selecting them."
  • If it is a library release, don't attach anything, as the libraries can be recreated from the tagged source tree, and in the future, we'll publish to a public Maven repository.

"Publish release"

Clean ./doc/release-notes.md and commit. 

cat /dev/null > ./doc/release-notes.md
git add ./doc/release-notes.md
git commit -m "cleaned ./doc/release-notes.md post-release"
git push

Link to a Specific Line

Use #L<start>-L<end>

https://github.com/moby/moby/blob/master/oci/defaults.go#L14-L30

Issue Queries

https://help.github.com/articles/searching-issues-and-pull-requests/
is:issue is:open author:ovidiuf

Authentication

Create a Personal Access Token for Command Line

Creating a personal access token for the command line

This procedure describes creation of personal access tokens:

Profile-photo icon -> Drop Down -> Settings -> Developer settings -> Personal Access Tokens -> Generate a new token.

Token description:

OAuth scopes: To use your token to access repositories from the command line, select repo.

Make sure to copy your new personal access token now. You won’t be able to see it again!

Scopes:

Minimal GitHub PAT Permissions.png

Other PAT Operations:

GitHub Authentication for AWS CodePipeline

GitHub Authentication for AWS CodePipeline

Connecting with SSH

https://docs.github.com/en/enterprise-server@3.6/authentication/connecting-to-github-with-ssh

Use your current SSH key from ~/.ssh. If you don't have one, this is how you generate one:

Create the OpenSSH Private/Public Key Pair

Add the public key to the GitHub account: User Dropdown → Settings → SSH and GPG keys → New SSH key → Title, Key.

Test: 

ssh -T git@github.com

Hi ovidiu! You've successfully authenticated, but GitHub does not provide shell access.

Pull Request Procedures

https://help.github.com/en/articles/searching-issues-and-pull-requests

Search Pull Requests

Open Pull Requests

is:pr is:open

Based on the Branch They Are Merging Into

base: BASE_BRANCH

By Author

author: USERNAME

Merge an Approved Pull Request

https://help.github.com/en/articles/merging-a-pull-request
https://help.github.com/en/articles/about-pull-request-merges#squash-and-merge-your-pull-request-commits

There are three options:

  • Create a merge commit: all commits from the head branch will be added to the base branch with a merge commit. The commits on the head branch are preserved in the repository. The merge is performed using the --no-ff option.
  • Squash and merge: if the head branch contains multiple commits, they are squashed into single one. Then the resulting commit is merged into the base branch using the fast forward option. What if in the mean time, new work also occurred on the base branch? Most likely, a merge commit will be created. Verify that. This option might be useful if you try create a more streamlined Git history in your repository. Work-in-progress commits are helpful when working on a feature branch, but they aren’t necessarily important to retain in the Git history. If you squash these commits into one commit while merging to the default branch, you can retain the original changes with a clear Git history. Of course, squashing can be done prior to the pull request, based on logical considerations and commit boundaries.
  • Rebase and merge - all commits from the head branch are added on the base branch individually without a merge commit.

Insert a Suggestion within a Pull Request

Click on the Blue + → "Insert a Suggestion" icon:

InsertaSuggestion.png

Change the Base Branch of a Pull Request

https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request

Make a Pull Request from a Forked Repository

Forked Repository Operations

Create a Repository

  • Immediately after creating the repository with the UI, clone it locally.
  • Create and push the "develop" branch.

git checkout -b develop
# local change
git commit -m "'develop' init"
git push --set-upstream origin develop

  • Settings → General
    • Pull Requests
      • Enable "Automatically delete head branches"
      • Disable "Allow merge commits"
      • Leave "Allow squash merging" and "Allow rebase merging"
  • Settings → Branches → Default branch → Switch default branch to another branch (⇄ icon) → "develop"
  • Settings → Branches → Branch protection rules → Add Rule. For branch name pattern: "main", "develop"
    • Require pull request reviews before merging: Required approving reviewers 2,
    • Do not check "Dismiss stale pull request approvals when new commits are pushed", it's a pain.
    • "Require review from Code Owners" if Code Owners is setup for repository.
    • Prevent PR Merging on Failed Pipelines Enable "Require status checks to pass before merging". For more details see Require status checks to pass before merging.
    • "Require conversation resolution before merging"
    • Do not check "Do not allow bypassing the above settings". This will allow admins to merge without an approval. At the same time, it will allow the admins to push from command line on the branch, which may be a problem.
    • Do not check "Allow force pushes", this will prevent admins to accidentally force push from command line.
    • Create
  • Settings → Notifications → Address: space separate list → Use the OD group address. Setup notifications.
  • Settings → Collaborators & teams → Add a team with "Write" permissions.
Retrieved from "https://kb.novaordis.com/index.php?title=GitHub_Procedures&oldid=111567"