This Tutorial on GitHub Explains Concepts like GitHub Projects, Organization and Teams, Fork a Repository, Issues and Project Milestones, GitHub Wiki etc:
In the previous tutorial of the series of tutorials on GitHub, we saw how a developer can utilize the platform to store the Project-related artifacts and version control the same. We also saw the concepts around Pull requests, Merging, Branching and Protecting branches.
Well, that’s not all. In this tutorial, we will dig deeper and find out what else GitHub can do for developers.
Here is what we will focus on.
- Create Organization and Teams
- Fork a repository
- Create Issues and Project Milestones
- Create Project board
- Creating GitHub Wiki
What You Will Learn:
- Create Organization And Teams
- GitHub Fork
- GitHub Issues And Project Milestones
- GitHub Project Board
- GitHub Wiki For Documentation
- Recommended Reading
Create Organization And Teams
As a pre-cursor to this section, GitHub provides the following 3 types of accounts.
- Personal User Accounts wherein you can create unlimited public and private repositories and also invite collaborators.
- Organization Accounts which is primarily a concept of shared accounts and will see more in this section.
- Enterprise Account which is used by companies who manage the policies internally for the users using GitHub. This is typically used in an On-Premise version of the GitHub Enterprise.
In Part 1, we saw how a repository was created using one single personal account where that user was a single owner of the repository. This is suited for small scrum teams where you have 3 to 9 people or maybe some more people or to create a repository for a single project is fine.
But what if there are large Github projects needing multiple repositories and multiple teams access for the same for the execution? Here, we need to look at how GitHub Organization helps in grouping multiple repositories for a single large project. Thus, there will also be multiple owners as there would be multiple Repositories/Teams involved.
To start creating a new Organization, click on the + at the top right and select New Organization.
Select a plan accordingly. We will be using a free plan for now which is Team for Open Source.
Enter the details about the Organization and then click on Next.
Add the members to the organization and click on Complete Setup.
The next step is to start creating repositories as per the project needs and add teams to the same.
You could also click on Invite someone to add members to the organization just created. As members are added, the role can also be assigned as a member or owner. To do this go to the People Tab and select Change Role for that member.
Well, for now, we will retain 1 user as the Owner and the other as a member. Thus, the Owner can create multiple repositories and assign teams to the respective repositories.
Before we create repositories, let’s create teams first. Go to the Teams tab and click on New Team.
We will create 2 teams i.e. UI Team and Middleware Team.
Click on Create team. Once the team is created, you can add members to the team as shown below.
Similarly, create the other team and add members to it. Now you can see that there are 2 teams.
Let’s proceed to create repositories. So, as a scenario, now we will create 2 repositories i.e. one to hold UI related code and the other to hold middleware code. The teams will be assigned accordingly.
Go to the Repositories tab and create a New Repository.
Click on the Create repository button. Next is to provide UI Team access to the repository.
Go to the Teams tab. Click on the UI Team and go to the Repositories tab. Click on each team and add the repositories again from the Repositories tab.
Add the repository by entering the name of the repository.
Also ensure Write permission for the team members to this repository i.e. the team members can read, clone and push to this repository.
Similarly, do the above steps to add the Middleware repository to the other team. Thus, we now have an Organization with repositories within it and the teams as well. The team members can clone the repository for which they have access to and work on the same.
Fork a Repository and keep in sync with the original Repository.
In the previous sections and the previous tutorial, we saw repositories being created and source code added to it. Now, what if the teams would like to test some code changes when the original repository is not the place to do it.
A copy has to be created to experiment with any changes to the code by keeping the original repository intact. This is called GitHub Fork. To create a Fork, navigate to the repository which was created in the personal account and not the organization. Click on Fork on the top right-hand side.
Select the account where you need to fork the original repository. In this instance select the organization account where the repository will be forked.
The repository is now forked as Demo-Proj-Org/Demo_Project_Repo_VN. So, any experiments with the code can be done in the forked repository and not in the original repository.
If any changes have been done in the original repository, then the forked repository has to be in sync. Command-line options could be used to get the forked repository to be in sync but creating a pull request is a simpler option.
Assuming that a change is done to a file in the original repository, proceed to create a Pull Request.
Click on the link compare across forks.
Select the head as the original repository and base as the forked repository as shown and click on Create pull request.
Click on Merge pull request and confirm the merge.
The changes appear in the forked repository and are in sync with the original repository.
GitHub Issues And Project Milestones
Normally in every project, one needs to track tasks, defects, enhancements, etc as part of the progress. You can use the issues in GitHub to track all the above-mentioned ones along with the Project Boards.
With issues, you can associate the same with pull requests so that it can be automatically closed when the pull request is merged. Also, if there are open issues they can also be transferred to other repositories. In this section, we will see a lot more about how issues can be used.
Creating Issues and Milestones
Go to the main page of the repository and go to the Issues Tab. Click on New issue.
Assign it to a collaborator to work on, add Label to distinguish as an enhancement. A good practice is also to mention about the Milestone to track the progress of the issues raised.
Click on Submit a new issue.
The issue summary is displayed. Note that the issue number is #11 which will be referenced later.
The issue can also be transferred to another repository. The option to do it is at the bottom ‘Transfer issue’.
Add a due date to the milestone – R1. On the main page of the repository go to the Issues Tab and click on Milestones.
Edit the details for the Milestone R1 and add a due date. Save the changes once done.
The Milestone R1 now has 2 open issues and the % of completion can also be seen.
Click on the Milestone R1 to look at the issues to be delivered for this milestone. Issues can also be re-prioritized by moving the issues up and down.
Assuming there are multiple issues that are in Open/Close state and assigned to multiple collaborators. It is very essential to search for those issues which are based on certain criteria.
For Example, all issues assigned to you, all issues in open state, etc. GitHub provides the search option to filter on the issues and even pull requests.
Go to the Issues tab and in the filter box enter the criteria as follows.
For Example, all open issues in the Open state and Assigned to a collaborator.
type:issue state: open assignee:vniranjan2512 milestone:R1 label:enhancement
Associate Issues To Pull Request
When a Pull Request is referenced with a particular keyword & issue number and once merged the issue is automatically closed. Even if a commit is referenced with keyword & issue number, the issue is closed.
The keyword can be any i.e. close, closes, fixes, fix, resolve, resolves.
For Example, in the pull request or commit message mention closes #11.
Create a pull request and mention the keyword & reference number as shown in the message. Click on Create a pull request and merge.
The issue is automatically closed on the merge of the pull request. Bit of automation is definitely needed.
Create or Open New Issues From Source Code
For any code changes a new issue can be opened. With this, the URL to the line of code change is added to the issue. In a non- edit mode of the code click on the 3 dots (…) next to the line of code and select Reference in New Issue.
Issue details updated.
You can pin issue so that it makes it easier to find the issues and also avoid duplicate issues from being created.
Open the issue and in the right-hand bottom of the issue click on Pin issue.
The issue is now added above the issue list.
Note: A maximum of 3 issues can be pinned at any time.
GitHub Project Board
A project board in GitHub provides an easy way to visualize the issues. You can view the project progress and look at what issues are yet to be started, in progress and completed issues.
A project board in GitHub can be created based on Kanban templates which has a pre-defined workflow and can be customized as well. The example will showcase a board created based on the user account.
On the main page of the repository go to the Projects tab and create a New Project.
As you can see from above the project board helps to:
- Sort tasks
- Plan your project
- Automate your workflow
- Track progress
- Share status
- Close project
New Project Board with a basic Kanban Template.
The board is created with a workflow. Additional workflow columns can also be added as well by clicking on the + Add column.
The workflow can also be automated. For Example, if a new issue is created, it can directly be added to the To-Do status. Select the Manage automation option for that status.
Select the checkbox Newly added and click on Update automation. So, when a new issue is created, the project selected for the issue will automatically be added to the To-Do status. You can also drag and drop the existing issue to the status and move from one status to another.
To a column, you can also add notes which will ensure that you serve some important information about the issues in that column. Click on the +sign and add a note.
Click on Add.
GitHub Wiki For Documentation
One of the very important activities in any project is creating and maintaining documentation for your repository for the entire team to use. GitHub repository comes with support for creating such documentation using GitHub Wiki. So, all the information about your project and its usage can be captured in the wiki.
Wikis are available for public repositories in GitHub for free. Wikis use Open source Markup library. We will see how to use this library while writing wikis.
Enabling Wiki Support For Repository
On the main page of the repository, click on the Settings tab and ensure that the Wikis option is selected under the Features section.
Create A GitHub Wiki
On the main page of the repository go to the Wiki tab. Click on Create the first page.
Enter a title and add text to the Wiki. Also, you can use the formatting option using Markdown support. Click on the Save page once done.
Note in the above content # is for heading1, ## is for heading2, ### is for heading3. * is used for unordered listing. The preview will be as shown below.
On the Wiki tab click on + Add a Custom footer.
Add the content and save page.
Open any saved Wiki and you will see the footer.
On the wiki tab click on + Add a custom sidebar.
Add content for the sidebar and save the page.
Open any wiki and you will see the sidebar.
View Wiki History
In history, you can look at who made the change, commit messages and the date on which the change was made.
Open Wiki and edit the page. Click on Page history, on the right side.
Click on Hash to look at the changes. Select the revisions to compare changes and revert changes of a newer revision. Click on Revert changes.
The changes are reverted to the older revision.
Note: You can revert the changes based on the permission to edit the Wiki.
In Part 1 and Part 2 of the GitHub series we have seen about Version control activities, Creating repositories, Pull Requests, Branches, Code reviews, Organizations & teams, Fork a Repository, Labels, Milestones, Issues, GitHub Projects, Wikis.
In our upcoming tutorial, we will look at creating releases, integration with Jira and few Git commands that will aid developers before they push changes to the GitHub repository.
We hope all the developers would find this hands-on approach for GitHub useful in their projects.