diff --git a/README.md b/README.md index ed4a011..50b89ab 100644 --- a/README.md +++ b/README.md @@ -1 +1,21 @@ -# Linear Guide +# Software Project Management Workflows + +This README is intended for beginners in Linear issues and GitHub pull requests. + +Navigate to your intended docs to kickstart this tutorial. + +## Table of Contents +1. [The What and How of Linear Issue](https://yong-zaii.github.io/Linear-Guide/docs/Linear-Issue). + 1. Creating a Linear issue. + 2. Editing a Linear issue. +2. [Good GitHub Practices](https://yong-zaii.github.io/Linear-Guide/docs/GitHub-Practices). + 1. Writing a good commit message. +3. [The What and How of GitHub-Linear Workflows](https://yong-zaii.github.io/Linear-Guide/docs/GitHub-Linear). + 1. Linking GitHub commit to a Linear issue. + 2. Linking GitHub pull request to a Linear issue. + 3. Linking multiple PRs to a Linear issue. + 4. Linking a PR to multiple Linear issues. + 5. Reviewing a pull request. + + +## More to be updated... diff --git a/docs/GitHub-Linear.md b/docs/GitHub-Linear.md new file mode 100644 index 0000000..f49bd2b --- /dev/null +++ b/docs/GitHub-Linear.md @@ -0,0 +1,233 @@ +# The What and How of GitHub-Linear Workflows + +This documentation introduces you to the automated workflows between GitHub commits and pull requests to Linear issues. + +## Table of Contents +1. [Linking GitHub commit to a Linear issue](#link-commit-linear). + 1. [GitHub method](#github-method). + 2. [GitHub Desktop](#github-desktop). + 3. [Git method](#git-method). +2. [Linking GitHub pull request to a Linear issue](#link-pr-linear). +3. [Linking multiple PRs to a Linear issue](#link-multiple-pr). +4. [Linking a PR to multiple Linear issues](#link-multiple-linear). +5. [Reviewing a pull request](#review-pr-linear). + + +## Linking GitHub commit to a Linear issue + +In order to link a commit and a pull request to a Linear issue, the general idea is to copy the branch name from Linear issue and use it as the branch name in GitHub. Then, when a pull request (PR) for that branch is opened, the title of the PR must contain the Linear issue ID. + + + +### i. GitHub method + +You can use this method if you want to edit the files directly in GitHub repository without going into IDE or code editor. +Given that you have a Linear issue as follows: +> TV-14 Change the hompage contents to 'Hello World' + +1. In GitHub, select a file that you want to change. In our example, we will choose src -> App.js file. + +2. Edit the file. + +3. Copy the git branch name from the Linear issue that you want to link to. + +

+ +

+ +4. Important After you have copied the branch name, select 'Create a new branch...' and key in the copied branch name. + +

+ +

+ +5. Enter a commit title according to the guide, which is the label followed by the title of the Linear issue. In this case, the label is 'Feature'. So, our commit title will look like this: feat: Change the homepage contents to 'Hello World' + +

+ +

+ +6. Click 'Propose changes'. + +7. Continue at [Linking GitHub PR to a Linear issue](#link-pr-linear). + + +### ii. GitHub Desktop + +This is the preferred method for people who do not use Git to commit to GitHub repository. For this method, you need to have [GitHub Desktop](https://desktop.github.com/) and [VS Code](https://code.visualstudio.com/) installed in your computer. +Given that you have a Linear issue as follows: +> TV-15 Change the hompage contents to 'Bonjour World' + +1. Make sure you have cloned the repository. + +2. Copy the git branch name from the Linear issue that you want to link to (Refer to [step 3](#copy-branch-name) in GitHub Method). + +3. Important After you have copied the branch name, create a new branch using the copied branch name. + +

+ + +

+ +4. Click 'Open in Visual Studio Code'. + +5. In VS Code, select a file that you want to change. In our example, we will choose src -> App.js file. + +6. Edit and save the file. + +7. Go back to GitHub Desktop, enter a commit title according to the guide, which is the label followed by the title of the Linear issue. In this case, the label is 'Feature'. So, our commit title will look like this: feat: Change the homepage contents to 'Boujour World' + +

+ +

+ +8. Click 'commit to {branch name}'. Then, click 'Publish branch'. + +

+ +

+ +9. Click 'Create Pull Request'. + +

+ +

+ +10. Continue at [Linking GitHub PR to a Linear issue](#link-pr-linear). + + +### iii. Git Method + +This is the preferred method for people who want to use Git to commit to GitHub repository. For this method, you can use any IDE or code editor you like. +In our example, we will use VS Code. +Given that you have a Linear issue as follows: +> TV-14 Change the hompage contents to 'Hello World' + +1. Make sure you have cloned the repository. + +2. Copy the git branch name from the Linear issue that you want to link to (Refer to [step 3](#copy-branch-name) in GitHub Method). + +3. Important After you have copied the branch name, create a new branch using the copied branch name with the following command: + Example: git branch ti0003ng/tv-14. + +4. After the new branch ti0003ng/tv-14 has been created, enter git checkout ti0003ng/tv-14 to navigate to the new branch. + +5. Edit and save the file in VS Code. + +6. Enter git status to check the status of the files to be committed. + +7. Enter git add . to select all files that are modified. + +8. Enter git commit -m "feat: Change the homepage contents to 'Hello World'" to commit to the new branch remotely. + +9. Enter git push origin ti0003ng/tv-14 to publish the new branch on GitHub repository. + +10. Go to GitHub, open the new branch created in GitHub repository and create a new pull request. + +11. Continue at [Linking GitHub PR to a Linear issue](#link-pr-linear). + + +## Linking GitHub PR to a Linear issue + +1. Now, you have arrived on the PR creation page. + +

+ +

+ +2. Important Enter the issue ID in square brackets right after the PR title. The issue ID can be found in the Linear issue. In this case, the issue ID is TV-14. + +

+ +

+ +3. Click 'Create pull request' and voila, the Linear issue is automatically updated to 'In Progress' and later to 'In Review' status. + +

+ + +

+ + + +## Linking multiple PRs to a Linear issue + +The idea is similar to [Linking GitHub commit to a Linear issue](#link-commit-linear) followed by [Linking GitHub pull request to a Linear issue](#link-pr-linear). Hence, you are advised to read the two sections before proceeding. +Given that you have a new Linear issue as follows: +> TV-17 Make the title more prominent + +1. Assume you have a branch called ti0003ng/tv-17. You have also created a pull request for this branch and linked it to the Linear issue: TV-17. + +

+ +

+ +2. Now, create a new branch such as ti0003ng/tv-17-2. With this new branch, create a new pull request and link it to the Linear issue. + +

+ +

+ +3. Linear will automatically detect the 2nd PR and link it to TV-17. + +

+ +

+ + +## Linking a PR to multiple Linear issues + +The idea is similar to [Linking GitHub commit to a Linear issue](#link-commit-linear) followed by [Linking GitHub pull request to a Linear issue](#link-pr-linear). Hence, you are advised to read the two sections before proceeding. +Given that you have two new Linear issue as follows: +> TV-18 Change the font size + +> TV-19 Change the font type + +1. Now, create a new branch such as ti0003ng/tv-18 or ti0003ng/tv-19 or even better, style/change-font-style. + +

+ +

+ +2. With this new branch, create a new pull request. Important Enter the different issue IDs in separate square brackets right after the PR title. In this case, the PR title should look like this: style: Change font styles [TV-18] [TV-19]. + +

+ +

+ +3. Linear will automatically detect and link one PR to both issues. + + + +## Reviewing a PR + +In review a pull request, you can either comment, approve, or request changes from the pull request owner. In our example, we will only show the process of approving a pull request. Commenting and requesting changes share similar process. +A pull request will need at least one approval from any reviewer for the commit to be merged. Here, you will learn how to approve a pull request and merge it into the main branch. + +1. In the pull request page, click 'Files changed'. + +2. Click 'Review changes'. Here, we have three options - Comment, Approve and Request Changes. + +

+ +

+ +3. Select 'Approve' and then 'Submit review'. Now the pull request is ready to be merged into the main branch. + +4. Go back to the pull request page, click 'Merge pull request' and then 'Confirm merge'. + +

+ + +

+ +5. The Linear issue is automatically updated to 'Done' status. We have officially completed one Linear issue cycle. + +

+ +

+ + +## References + +Linear. (n.d.). *GitHub*. [https://linear.app/docs/github](https://linear.app/docs/github). \ No newline at end of file diff --git a/docs/GitHub-Practices.md b/docs/GitHub-Practices.md new file mode 100644 index 0000000..a7680d8 --- /dev/null +++ b/docs/GitHub-Practices.md @@ -0,0 +1,26 @@ +# The What and How of Good GitHub Practices + +This documentation contains the common good GitHub practices. + +## Table of Contents +1. [Writing a good commit message](#commit-message). + + + +## Writing a good commit message + +Every time when we create a new commit, we need to input the commit title/message. Here is the list of conventional commit messages type: +- feat: Adding a new feature +- fix: Fixing code/bug +- improvement: Improving or updating a section of the code +- refactor: Refactoring a section of the code +- style: Changes to styling of the website +- chore: Code maintenance/miscellaneous tasks +- test: Testing purpose +- docs: Documentation + + + +## References + +Ayodeji, B. (2019, Nov 28). *How to Write Good Commit Messages: A Practical Git Guide*. [https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/](https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/). \ No newline at end of file diff --git a/docs/Linear-Issue.md b/docs/Linear-Issue.md new file mode 100644 index 0000000..8b1e3d6 --- /dev/null +++ b/docs/Linear-Issue.md @@ -0,0 +1,44 @@ +# The What and How of Linear Issue + +This documentation contains the fundamentals of using Linear. + +## Table of Contents +1. [Creating a Linear issue](#create-issue). +2. [Editing a Linear issue](#edit-issue). + + + +## Creating a Linear issue + +1. Select your team. In our example, we will select 'Test & Verify' team. + +2. Select 'Issues' tab. + +3. Click on the '+' button on the top right and the issue creation window will be opened. + +4. Now, key in the necessary information including title, description (if any), set the status, priority, assignee, label, as well as due date. + +5. After that, save the issue and voila, a Linear issue is created. + +

+ +

+ + + +## Editing a Linear issue + +1. From the list of issues, select the issue that you want to edit. + +

+ +

+ +2. You can change the title, add description, change status, priority, assignee, label, as well as due date. + + +## References + +Linear. (n.d.). *Create issues*. [https://linear.app/docs/creating-issues](https://linear.app/docs/creating-issues). + +Linear. (n.d.). *Edit issues*. [https://linear.app/docs/editing-issues](https://linear.app/docs/editing-issues). \ No newline at end of file diff --git a/photos/GitHub_Branch_Name.png b/photos/GitHub_Branch_Name.png new file mode 100644 index 0000000..0a40e9c Binary files /dev/null and b/photos/GitHub_Branch_Name.png differ diff --git a/photos/GitHub_Commit_Issue_2.png b/photos/GitHub_Commit_Issue_2.png new file mode 100644 index 0000000..35ec29f Binary files /dev/null and b/photos/GitHub_Commit_Issue_2.png differ diff --git a/photos/GitHub_Commit_Title.png b/photos/GitHub_Commit_Title.png new file mode 100644 index 0000000..571a5cf Binary files /dev/null and b/photos/GitHub_Commit_Title.png differ diff --git a/photos/GitHub_Confirm_Merge.png b/photos/GitHub_Confirm_Merge.png new file mode 100644 index 0000000..8d1611e Binary files /dev/null and b/photos/GitHub_Confirm_Merge.png differ diff --git a/photos/GitHub_Delete_Branch.png b/photos/GitHub_Delete_Branch.png new file mode 100644 index 0000000..5fc62f1 Binary files /dev/null and b/photos/GitHub_Delete_Branch.png differ diff --git a/photos/GitHub_Desktop_Branch.png b/photos/GitHub_Desktop_Branch.png new file mode 100644 index 0000000..269cb36 Binary files /dev/null and b/photos/GitHub_Desktop_Branch.png differ diff --git a/photos/GitHub_Desktop_Commit_Title.png b/photos/GitHub_Desktop_Commit_Title.png new file mode 100644 index 0000000..7758ad3 Binary files /dev/null and b/photos/GitHub_Desktop_Commit_Title.png differ diff --git a/photos/GitHub_Desktop_New_Branch.png b/photos/GitHub_Desktop_New_Branch.png new file mode 100644 index 0000000..e40326d Binary files /dev/null and b/photos/GitHub_Desktop_New_Branch.png differ diff --git a/photos/GitHub_Desktop_PR.png b/photos/GitHub_Desktop_PR.png new file mode 100644 index 0000000..4cb8c0a Binary files /dev/null and b/photos/GitHub_Desktop_PR.png differ diff --git a/photos/GitHub_Desktop_Publish.png b/photos/GitHub_Desktop_Publish.png new file mode 100644 index 0000000..c3183c3 Binary files /dev/null and b/photos/GitHub_Desktop_Publish.png differ diff --git a/photos/GitHub_Merge_PR.png b/photos/GitHub_Merge_PR.png new file mode 100644 index 0000000..ab4e85b Binary files /dev/null and b/photos/GitHub_Merge_PR.png differ diff --git a/photos/GitHub_PR.png b/photos/GitHub_PR.png new file mode 100644 index 0000000..dafce2b Binary files /dev/null and b/photos/GitHub_PR.png differ diff --git a/photos/GitHub_PR_2_Issue_1.png b/photos/GitHub_PR_2_Issue_1.png new file mode 100644 index 0000000..5bc4763 Binary files /dev/null and b/photos/GitHub_PR_2_Issue_1.png differ diff --git a/photos/GitHub_PR_Issue_2.png b/photos/GitHub_PR_Issue_2.png new file mode 100644 index 0000000..e30e706 Binary files /dev/null and b/photos/GitHub_PR_Issue_2.png differ diff --git a/photos/GitHub_PR_Review.png b/photos/GitHub_PR_Review.png new file mode 100644 index 0000000..58fd7a6 Binary files /dev/null and b/photos/GitHub_PR_Review.png differ diff --git a/photos/GitHub_PR_Title_IssueID.png b/photos/GitHub_PR_Title_IssueID.png new file mode 100644 index 0000000..4504ac4 Binary files /dev/null and b/photos/GitHub_PR_Title_IssueID.png differ diff --git a/photos/GitHub_Review_Changes.png b/photos/GitHub_Review_Changes.png new file mode 100644 index 0000000..88e904f Binary files /dev/null and b/photos/GitHub_Review_Changes.png differ diff --git a/photos/Linear_Copy_Branch_Name.png b/photos/Linear_Copy_Branch_Name.png new file mode 100644 index 0000000..c4790ae Binary files /dev/null and b/photos/Linear_Copy_Branch_Name.png differ diff --git a/photos/Linear_Created_Issue.png b/photos/Linear_Created_Issue.png new file mode 100644 index 0000000..c96073a Binary files /dev/null and b/photos/Linear_Created_Issue.png differ diff --git a/photos/Linear_Done.png b/photos/Linear_Done.png new file mode 100644 index 0000000..77cd0cd Binary files /dev/null and b/photos/Linear_Done.png differ diff --git a/photos/Linear_In_Progress.png b/photos/Linear_In_Progress.png new file mode 100644 index 0000000..7c8804a Binary files /dev/null and b/photos/Linear_In_Progress.png differ diff --git a/photos/Linear_In_Review.png b/photos/Linear_In_Review.png new file mode 100644 index 0000000..2a47b19 Binary files /dev/null and b/photos/Linear_In_Review.png differ diff --git a/photos/Linear_Issue_List.png b/photos/Linear_Issue_List.png new file mode 100644 index 0000000..18dabef Binary files /dev/null and b/photos/Linear_Issue_List.png differ diff --git a/photos/Linear_Multiple_PR_1.png b/photos/Linear_Multiple_PR_1.png new file mode 100644 index 0000000..282ecb8 Binary files /dev/null and b/photos/Linear_Multiple_PR_1.png differ diff --git a/photos/Linear_Multiple_PR_2.png b/photos/Linear_Multiple_PR_2.png new file mode 100644 index 0000000..bd9d601 Binary files /dev/null and b/photos/Linear_Multiple_PR_2.png differ diff --git a/photos/README.md b/photos/README.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/photos/README.md @@ -0,0 +1 @@ +