Task Tracking via Issues
GitHub Issues is how we do our task tracking at the moment. They allow us to create a post for a task that needs doing, and for members to claim that task. They can also automatically be linked to Branches and Pull Requests for ease of development and submission.
You can find the Issues tab along the top bar in the GitHub repo underneath the repo name. It should be the second button.
Once you find the issues, there are are few important things to look at before determining whether you wish to work on it.
Each issue is marked with labels. These help you to properly sort through issues that fit you most.
- Draft: This means that an issue is currently being written, and isn't ready to be worked on yet.
- Approved: This means that the issue has passed the draft stage, and is ready to be worked on.
- Difficulty: This label is denoted by a capital D followed by a number. The higher the number, the more difficult the issue is estimated to be.
- Priority: This label is denoted by a capital P followed by a number. The higher the number, the more important/time sensitive the issue is.
- New Member: This means that the issue is particularly friendly to newer members. It doesn't require a lot of prior knowledge of the codebase.
The description gives an overview of what the task is and why it matters.
The implementation steps gives you a general order to do things in, and gives specific deliverables that allow you to know when the task is complete.
This is just an estimate of how long the task should take, or when it needs to be done by.
This is located at the right of the issue. It shows who, if anyone, is already assigned to an issue. You may not claim an already assigned issue unless the current assignee has agreed to let you join.
After you have found an issue to work on, it's time to claim it! There are only a few steps to claiming an issue.
- Make sure you have fully read through the description and implementation steps! These are an important guide to completing the issue.
- Notify the Project Manager of you selection. You do not have to wait for their confirmation to claim the issue, this notification is mostly just to help them keep track of things
- Assign yourself to the issue. You can do this by going to the Assignees section on the right and clicking
Assign yourself - Create a branch for the issue. You will be writing and committing all of your code within this branch. You can do this by going to the Development section on the right (it will be towards the bottom of the column), and clicking
Create a branch. You can leave the branch name as the default, and press the greenCreate branchbutton.
You now have an issue! Make sure to attend the ChessBots meetings. It really helps to have people there when you have a question.
You've created a branch through GitHub, but now you have to make sure to select it in VSCode. Go down to the bottom right when you have the repo open in VSCode. You should see a button that says main. After clicking it, there should be dropdown near the top middle. Select the branch name that you just created.
After selecting your branch, your are free to make any changes needed to complete your issue. Make sure to save any files you make changes in (Ctrl+s). To commit changes, Go to the left bar in VSCode. Go to the third button down (Should show 3 circles connected by lines. When hovering, the label will say Source Control). After going to this Source Control tab, enter a commit message into the message text box. This message should explain what changes you made. Under your changes, hover over a file and press the + button to stage a change. When you press Commit, it will save all of the staged changes to the branch. You can now click the Sync Changes button to push those changes to GitHub.
It's best practice to commit often after every small change. This allows reverting to those previous states if something goes wrong. It also shows a timeline of progress, as well as allowing others to take a look at your changes.
Before submitting an issue, make sure to review the Implementation Steps. Confirm that you have completed and committed all of them, and the issue is fully complete.
Pull requests are requests to merge changes you have made to the codebase into the main branch. By making a pull request, you are assuming that the code you have made has as few bugs as possible and can be reliably merged into the main branch of the codebase. When you make a pull request, your code will be reviewed by the Project Manager or another trusted senior member for errors. After reviewing, the members may send feedback on your code for you to work on. After some back and forth, your code will eventually be approved and finally merged into main for everyone to see.
On the top of the GitHub Repo, look for a tab called Pull Requests.
By clicking on the tab, it should pull you up to the GitHub Request page filled with Open and Closed request files. In order to make a new pull request, click on the Green button that says New Pull Request. This will initially pull up all the branches applied to that Repo. Now, select the branch you were working with.
For example, if you were working with Issue #3, pull up the branch for Issue #3. Review the page and verify whether those changes are correct.
When you finalized the changes on that pull request, click on Create Pull Request. The Project Manager will review the pull request and verify the files and if everything is done right, they will pull your request into the Repo.
Happy Coding! 🤖