GitHub Process
This section requires foundational knowledge of Git and GitHub. If you do not know how Git and GitHub work, you can find educational resources at the following links:
Code editors such as IntelliSense-based products or VS Code integrate well with Git and support you in staging, committing, pushing, and pulling.
A good practice for authoring is laid out in the following process. It is not necessary to worry - the process is leaner than it looks at first glance:
---
config:
theme: redox
---
stateDiagram-v2
CreateIssue: Create issue (1)
Prepare: Prepare (2)
Publish: Publish (3)
Review: Review (4)
Merge: Merge pull request (5)
Close: Close issue (6)
[*] --> CreateIssue: Issue non-existent
CreateIssue --> Prepare
[*] --> Prepare: Issue exists
state Prepare {
AssignIssue: Assign issue (2.1)
CreateBranch: Create branch (2.2)
Edit: Edit (2.3)
Commit: Commit (2.4)
[*] --> AssignIssue
AssignIssue --> CreateBranch
CreateBranch --> Edit
Edit --> Commit
Commit --> Edit: Not ready for publication
Commit --> [*]: Ready for publication
}
Prepare --> Publish
state Publish {
CreatePullRequest: Create pull request (3.1)
DraftPr: Set draft (3.2)
Edit2: Edit (3.3)
Commit2: Commit & push (3.4)
AddReviewers: Add reviewers (3.5)
[*] --> CreatePullRequest
state fork_state <<fork>>
CreatePullRequest --> fork_state
fork_state --> DraftPr: Not ready for review
Commit2 --> Edit2: Not ready for review
DraftPr --> Edit2
Edit2 --> Commit2
fork_state --> AddReviewers
state join_state <<join>>
Commit2 --> join_state: Ready for review
fork_state --> join_state: Ready for review
AddReviewers --> join_state
join_state --> [*]
}
Publish --> Review
state Review {
WaitForReview: Wait for review result (4.1)
Approve: Approval received (4.2)
Comment: Comments received (4.3)
RequestChanges: Changes requested (4.4)
Resolve: Resolve (4.5)
[*] --> WaitForReview
WaitForReview --> Approve
WaitForReview --> Comment
WaitForReview --> RequestChanges
Approve --> [*]
Comment --> Resolve
RequestChanges --> Resolve
Resolve --> WaitForReview
}
Review --> Merge
Merge --> Close
Close --> [*]
The following subsections describe the process steps identified by the numbers in parentheses above.
If you plan to craft content, there should always be an issue tied to the work you are doing to establish traceability from the problem statement down to the solution. Issues get unique numbers which can be used to relate between issues, pull requests and Git commits. It allows for an author/reviewer/editor to efficiently identify who edited what and why in a project.
Important
Always create an issue before starting to work on a project
Once an issue is present, you can prepare an initial draft of your work. Step 2 describes preparational steps towards a pull request.
To signify who is the main editor of an issue, you need to assign yourself to the issue. It is possible to assign up to 10 people; however, it is not preferred to do so as it may blur the responsibility.
On the issue page, assign yourself to the issue by clicking the link on the right side:
Before you can commit contents to Git, a Git branch is required. GitHub can automatically connect a branch name to an issue by using the Create a branch link on the issue page:
This opens a new dialog:
Typically, the fields and checkboxes can be left as they are. Once you click Create branch, GitHub will provide you with command line instructions to checkout the branch locally:
The button within the red circle copies the commands to the clipboard.
Edit files according to your requirements. Asciidoc editing information can be found here.
Every once in a while, (intermediate) states of your work should be committed to Git. Git requires you to pass commit messages for which there are plenty of philosophies around as to what those messages should look like.
The Conventional Commits Initiative provides a solid "specification for adding human and machine readable meaning to commit messages." As the specification aims for commits containing software code, this guideline suggests to use the following subset and commit message style:
<type>: #<issue-id> <text>
where
-
<type>is-
featfor any new, changed or deleted content -
fixfor editorial changes such as misspellings -
chorefor rephrasing or refactoring content
-
-
<issue-id>is the issue id that is tied to the changes committed, creating a link between the edit and the issue -
<text>is a brief description of the changes
Once you feel like your work has reached a significant state or want to continue with your work at a later time and perhaps on a different machine, you can publish your commits to GitHub. You may either push without doing anything further or push and create a pull request.
This step describes the latter option.
Whenever you push commits to GitHub for which the pushed branch does not relate with a pull request, GitHub asks you to create one. This is the easiest way of setting up a pull request. Just click the button and confirm:
You should assign yourself as an Assignee, add reviewers and make this pull request a draft if it is not ready to be reviewed yet:
Note
Assigning assignees and reviewers and setting a draft state can also be done later in the pull request process.
If not done in step 3.1 already, make your pull request a draft if not ready to be reviewed yet.
See 2.3 Edit.
See 2.4 Commit followed by pushing to GitHub.
If not done in step 3.1 already, you should add reviewers at some point as you need to receive at least one approval to merge your changes.
Once you add at least one reviewer and your pull request is not in draft state anymore, the reviewer(s) are implicitly requested to review your changes and submit a review result:
More information on pull requests can be found here.
Caution
Reviewers and assignees should not solely rely on the Asciidoc code, but also review the resulting document.
Caution
By default, a repository is not configured in a way that approvals are required. In order to increase the quality of the main branch, merging without approval should be disabled in the configuration by protecting the main branch
Your changes are ok and the pull request is ready to be merged.
There are comments that should be discussed or worked on. If configured accordingly, you cannot merge until the comments are resolved or there is at least one approval by any reviewer.
There are comments that must be resolved. If configured accordingly, you cannot merge until the comments are resolved.
Resolving comments is the process of discussing the comment online or in a peer review, followed by incorporating the changes into the branch associated with the pull request.
After the review, you can merge your changes to the main branch. The preferred way of merging to main is to squash and merge. This creates a linear history of changes, without including every individual commit message in the history of the main branch:
Caution
Creating merge commits should be disabled in the project configuration
If you initially created the branch from the issue dialog, closing the connected pull request automatically closes the issue as well. Otherwise, you need to manually hit the Close issue button on the issue page.