- Documentation and resources on how to use GitHub for Project 3
This is a group project. As such, you're expected to equally contribute to all parts of the project. To ensure everyone is contributing, we have moved this project entirely to GitHub and will use GitHub logs to understand your contributions. To fully leverage the features that GitHub offers, you have to be familiar with what they are and how to use them.
The goal of this project is to get you familiar with the creative process of software development for a general purpose use and how to use data structures or algorithms for those applications. To go with the professional development that the project offers in terms of general use application, you will also get more familiar with version control and GitHub platform to facilitate the collaborative work with extensive planning and organization abilities.
This step-by-step process is linked in this video if you aren't familiar with GitHub:
- Introduction to GitHub - General GitHub Features - Has chapters and closed-captions
The following video has instructions on local development using Git and GitHub:
- Local Development with Git and GitHub - Has chapters and closed-captions
To illustrate the development process, we've also made a demo video to show how the GitHub flow looks like on an example:
- Mastering GitHub Workflow - Has chapters and closed-captions
Here are the instructions on how to Collaborate for Project 3 which are similar to what was covered in the Introduction to GitHub video. You may skip reading these if you have watched that video:
This is a template repository. If you want to know more about those, feel free to follow this link to the GitHub documenation about templates and how to create them. You've used templates before for projects 1 and 2, and you will use it now, too.
The first step of your project is to make your own repository for your own project that will host your source code and documentation. Only one member of the team needs to create a repo and everyone else copies that repo using git clone.
- Navigate to the main page of the repository.
- Above the file list, in line with the repository name, click on the big green button saying "Use this template"
- Select "Create a new repository" (This step is important. Do not open in codespace. Make your own repository for your own project.)
Choose a descriptive name for your repository. This is part of some good practices about your GitHub repos. For this project, make sure to also make your repository public. The project is fully yours and you have all of the creative freedom, so feel free to use it as a part of your professional portfolio.
Since this is a group project, you are all expected to evenly contribute to the repository. Regardless of if you're working on the code, the documentation, or the video, you all have to have access to the repository since that is the only submission for this part of the project.
To add collaborators to you repository, navigate to the main page of the repository and click Settings.
- In the "Access" section of the side bar, click Collaborators & teams
- Under "Manage access", click Add people
- In the search field, type the username or email of the person you want to add to the repository.
- Once you found the person you want to add as a collaborator, you can select the role and permissions the person has on the repo. It is suggested that you add your group members as owners to make susre you all have even access to the repository.
More information about collaborators.
During the development of your software, you will have to perform several tasks. In project 3a, you agreed on how you will distribute these tasks. GitHub has several features that can help you keep track of these, so please make sure to use them.
Issues in GitHub is one of the most useful features when it comes to progress tracking. The platform allows you to set Milestones, which have due dates (very useful if you want to have weekly progress meter). Each Milestone can have several tasks called Issues in GitHub, which have the descriptions on what needs to be done.
Issues offer several organizational options that you should use:
- Issue ID number: Automatically generated by Git. Use these in your commit messages to refer to issues you solved in that merge.
- Issue name: Short name for the issue. Issues are meant to be very atomic, so the names should be something like: "Implement Left Rotation for AVL Tree".
- Issue description: Detailed description of the issue. This includes potential ideas on how to solve the problem that the issue presents, specific steps to be followed, or details on how the issue was encountered/discovered if this is a bug.
- Tags/labels: Issues can range from new features to discovered bugs, and tags allow you to organize the issues based on the type. You can create new tags/labels to fit your own project needs.
- Milestones: Adding a milestone for the Issue helps keep team on track because it sets a due date for that particular fix or implementation.
- Assignee: GitHub also offers you to assign the Issue to a particular user. This means that they are in charge of resolving that issue, and helps keep track of what tasks need to be done by whom. Make sure to use this feature for yourself and your team because it will help you keep track of how evenly the work is distributed.
- Tasklists: Each issue can be accompanied by a tasklist that involves steps/ideas on how to solve the problem. For example, this can involve some very high level pseudocode for the solution (e.g. Insert into PageRank: "Check if From page is in map", "Check if To page is in map", "Insert To", "Add From at To").
Once you have the initial tasks distributed as issues in your repo, your development should involve separate branches based on the tasks you do. Making a branch means that you have a safe copy of the code to work on in a sandbox style environment. This ensures that if you do something on your branch that messes up the already working code in the main branch, your mistake would not affect the main code and you can start over to ensure you don't encounter the same problem.
To make a branch, you open the main page of the repository (Code).
- Click on the branch () dropdown menu and click "View all branches"
- Create a big green button that says "New Branch"
- Give the branch a descriptive name
To delete a branch, open the tab with all branches and click on the bin () symbol at the end of the line with the branch you want to delete.
Commits are a way to update the repository with the changes you made. Each commit has information about who made the change, what changes were made, when the change was made, and a message that describes the changes (and/or if it refers to an Issue).
Commits are very important part of collaboration and should follow an agreed on convention for the team. Each commit also offers a way to organize the changes because it shows a very short concise description of the change made. As such, make sure to commit frequently and that each commit solves only one issue. As with Issues, your commits should be atomic (contains only one change, e.g. Feat: implement user input parsing for calculator to split string into tokens (Issue #1)).
- Keep it short (less than 150 characters total)
- Committing fewer changes at a time can help with this
- Use the imperative mood
- This convention aligns with commit messages generated by commands like git merge and git revert
- Consistency enhances speed of reading comprehension
- Tends to be more concise than the other moods
- Specify the type of commit (Link to ISSUE):
- feat: The new feature you're adding to a particular application
- fix: A bug fix
- style: Feature and updates related to styling
- refactor: Refactoring a specific section of the codebase
- test: Everything related to testing
- docs: Everything related to documentation
- chore: Regular code maintenance.[ You can also use emojis to represent commit types]
- Remove unnecessary punctuation marks
- Do not end the subject line with a period
- Capitalize the subject line and each paragraph
- Use the body to explain what changes you have made and why you made them.
- Information in commit messages:
- Issue it fixes
- Why the change was made
- Where the change was made
- If it's a fix, describe the bug
- Be CONCISE.
- "." - Very Bad (What does this even mean?)
- "m" - Very Bad (Okay?)
- ":)" - Very Bad (I hope your team members understand what this means because I don't)
- "main function" - Bad (What about it?)
- "First commit" - Bad (Congratulations?)
- "Update main.cpp" - Better but still bad (What changed?)
- "added mergesort.h, will add std::chrono later" - A bit better (Future plans shouldn't be the main point of a message. What does this commit change?)
- "removed empty line from bottom of dictionary and updated UI" - Good (But stick to one change per commit)
- "added filter buttons to sort menu" - Very Good (Use imperative mood and capitalize the messages, but the content of the message is excellent)
"A pull request is a proposal to merge a set of changes from one branch into another. In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase. Pull requests display the differences, or diffs, between the content in the source branch and the content in the target branch." About Pull Requests in GitHub
Once you've made commits and are done working on the feature your branch was for, you should make a pull request. A pull request is meant to allow your teammates to review your changes, give you feedback, and the merge all the functional code into one central location (main branch).
If you've made a mistake (happens to the best of us) in the changes you've made and committed, pushed, or merged, you can undo the majority of those changes using Git CLI. This guide allows you to interactively navigate through the resources based on the actions you've taken to find the solution for your problem.
README files are formatted using Markdown in GitHub. If you're not familiar with Markdown, or if you need some syntax information, you can find syntax and tips in Markdown resource file. In addition to README files being formatted using Markdown, you can use the same syntax in your commit messages, your issues, and milestones to format any text.
- GitHub Docs
- GitHub Desktop
- GitHub Get Started
- GitHub Repositories
- GitHub Pull Requests
- GitHub Issues
These sites are specifically referred to in the rest of the documentation provided.
- Best practices
- Quickstart
- Creating from Template
- READMEs
- Repo visibility
- Teams and Collaboration
- Working with Files