CodeNewbie Community

Cover image for How To Use GitHub For Project Collaboration โ€” Based on Agile Method
Ayu Adiati
Ayu Adiati

Posted on • Updated on • Originally published at adiati.com

How To Use GitHub For Project Collaboration โ€” Based on Agile Method

Hello Fellow CodeNewbies ๐Ÿ‘‹,

A few months ago, I had a great experience participating in a project collaboration program with The Collab Lab. I can't thank The Collab Lab enough for giving me the opportunity and experience to learn how to collaborate with other developers ๐Ÿ’–.

Based on that experience, I want to share with you what I learned.
So, in this article, I will walk you through how to use GitHub for project collaboration based on the Agile method.
Without further ado, let's start! ๐Ÿ˜„


Setup the collaboration environment on GitHub

1. Create a repo for the collaboration

One of the collaborators will create a repo on their GitHub. It will be the repo for all collaborators to push their changes. This remote repo is what we call the origin repo.

  • On the GitHub homepage, click on the "New" green button at the left bar.

create-new-repo-button-github.JPG
It will navigate you to the "Create a new repository" page.

  • Fill out the form and click the "Create repository" button.

create-new-repo.JPG

  • Copy and paste one of the options on the command line and click enter.
    • If you haven't set up the local repo, follow the โ€ฆor create a new repository on the command line. Replace the first commit commit message with your own.
    • If you already have a local repo set up, follow the โ€ฆor push an existing repository from the command line.
  • Click the "Code" tab.

    The initial files and folders are now available on the origin repo.

2. Add collaborators

  • On the GitHub repo, go to the "Settings" tab.
  • At the left bar, click on the "Collaborators".

collaborators-github.JPG

  • Click the "Add people" button.

add-people.JPG

  • Enter the collaborator's GitHub username, full name, or email they use for GitHub, then click the "Add to this repository" button.

add-collaborator.JPG
You can see the collaborators in the "Contributors" list at the right bar on the repo's homepage.

contributors-list.JPG

3. Create issues

Whether you do a solo project or team project, breaking the tasks into small chunks is a good practice.
Put these small chunks as issues on GitHub.

  • Go to the "Issues" tab on the repo homepage.
  • Click the "New issue" button.

new-issue.JPG

  • Add the title and the description.
  • Add the assignees if you have decided who will handle the issue. You can find this on the right bar.

add-assignees.JPG

๐Ÿ’ก Tips to write issues for adding a new feature to the project

  # As a user, I want to be able to add a new task to my to-do list
Enter fullscreen mode Exit fullscreen mode
  • Include Acceptance Criteria (AC).

Acceptance criteria are the predefined requirements that must be met, taking all possible scenarios into account, to consider a user story to be finished.
โ€” KnowledgeHut

  ## Acceptance Criteria
  - User is presented with a form to enter their new task.
  - When the user submits the form, the task will be saved to the database.
Enter fullscreen mode Exit fullscreen mode

4. Create project boards

kanban-boards.JPG

Depending on your team, you can opt in to have a project board as a tool to track your team's progress. In the Agile environment, it's common to use Kanban boards to see the state of the team's progress.

  • Navigate to the "Projects" tab.
  • Select the "Projects" โ€” I'm using the non-beta one โ€” and click the "New projects" button.

new-projects.JPG

  • Add the name of the project.
  • Select the project template as you find suitable for your team. For this example, I am using the "Basic kanban". This option creates the To Do, In Progres, and Done columns.

project-template.JPG

  • Click the "Create Project" button.

create-project.JPG

Now you can start to add the cards and, if necessary, some more columns.

โ“ How to add the cards and columns

  1. When you have issues available and want to add them in one of the columns.

    • Click on the "Add cards" tab on the right side, next to the filter bar.

    add-cards.JPG

    • Search for the issues. If you're not sure of the name of the issue, you can type type:issue. It will give you the list of the issues in the repo.

    search-issue.JPG

    • Drag and drop the issue to the target column.
  2. When you want to add a note in one of the columns.

    • Click on the "+" sign on the target column.

    add-to-do-card.JPG

    • Enter your note and click the "Add" button.

You can also change your note into an issue:

  • Click the three dots symbol on your note's card.

    three-dots-on-card.JPG

  • Select "Convert to issue".

    convert-to-issue.JPG

  • Write the title and the description of the issue. Then submit it by clicking the "Convert to issue" button.

convert-to-issue-form.JPG

You can also add more columns if you need. For example, if you want to have a column for "Ready to review" or "Ready to merge", etc.

  • Click "Add column" on the right side of the page.

    add-column.JPG

  • Enter the column name and click the "Create column" button.

  • Drag and drop the column to re-order.

You can start to use the board by dragging and dropping the cards between columns.

Start collaborating with Git and GitHub

Now that you have set up the collaboration environment, it's time to start the project!

There would be times when you are working on an issue by yourself.
But there would also be times when you tackle the same issue with others.

1. Create a working branch

When you're collaborating, it's always a good practice to create a new branch for you to work on your issue.
Creating a new branch will prevent you from pushing your changes directly into the main branch.

You might first want to be on the local main branch. Then create a new branch by running this command:

  git checkout -b branch-name
Enter fullscreen mode Exit fullscreen mode

Now you can start to work on your issue.

2. Pull the working branch

When you're working on the same issue with other collaborators, one of the collaborators creates a branch and pushes this branch to the origin repo.


Then the other collaborators will fetch the origin repo, pull, and navigate to this branch by running:

# fetch the origin repo
git fetch

# pull the working branch
git pull origin branch-name

# navigate to the branch
git checkout branch-name
Enter fullscreen mode Exit fullscreen mode

This process will let you and your teammates work on the issue in the same branch.

3. Push the working branch to the origin repo

You have finished working on the issue, and now you're ready to push your branch.

  • Run this command to stage your changes for commit.
  git add .
Enter fullscreen mode Exit fullscreen mode
  • Commit your changes.

Change the commit message to your message.

  git commit -m "Your commit message"
Enter fullscreen mode Exit fullscreen mode
  • Make sure your local repo is in the same state as the origin to assure that you are pushing the most updated changes.

    • Navigate to your local main branch by running this command:
    git checkout main
    
    • Pull the main branch from the origin repo to the local main branch.
    git pull
    

    If there is no update on the main branch, you can proceed to push your changes.
    But when there are changes:

    • Navigate to your working branch.
    git checkout branch-name
    
    • Merge the local main branch into your working branch.
    git merge branch-name main
    
  • Push your branch to the origin repo.

  git push origin branch-name
Enter fullscreen mode Exit fullscreen mode

โžก Add Co-authored-by: to commit message

When you're working on the same issue with others, you want to include them in your commit message. This way, all collaborators will commit together.

co-authored-commit.JPG

Below is how you want to write your commit message:

git commit -m "Add a component for adding task
>
>
> Co-authored-by: Jane Doe <jane@email.com>
> Co-authored-by: John <john@email.com>"
Enter fullscreen mode Exit fullscreen mode
๐Ÿ’ก Important to know
  1. Exclude the person who commits and pushes the branch from the "Co-authored-by:". Only collaborators other than this person get included with "Co-authored-by:" in the commit message.

  2. Commit messages are case-sensitive. So you need to make sure of these things:

  • Do not close the commit message with double-quotes (") before you add the "Co-authored-by:".
  • Always give two empty spaces before writing the line "Co-authored-by".
  • Make sure that there is no typo. It should be Co-authored-by:, with capital C at the beginning and a colon (:) at the end. Sometimes, it happens that there's a typo on the word "authored".
  • Ensure that the emails are associated with the collaborators' GitHub accounts.
  • Close the commit message with double-quotes (") after the last line of "Co-authored-by:".

You can read more about creating a commit with multiple authors here.

4. Create a pull request and merge

Now that you've pushed your branch to the repo, you can start to create a pull request.

  • Refresh the origin repo page on GitHub, then click the "Compare & pull request" button.

compare-pull-request.JPG

  • Enter the title and the description of the pull request. And then click the "Create pull request" button.

create-pull-request.JPG
If there is a conflict, you need first to solve it, then push it back to the origin repo.

  • If you want your teammates to review your code, add them to the "Reviewers" on the right side of the page.

add-reviewers.JPG

You can still add more commits to the pull request branch if you have more changes in this state.

  • After your teammate reviewed your pull request:

    • Make changes in the branch of your local repo if you need to. Then add, commit, and push them to your branch on the origin repo by running these commands:
      git add .
      git commit -m "Your commit message"
      git push origin branch-name
    
    • When they approve your changes, click the "Merge pull request" button.
  • You may want to delete the working branch on the origin repo. You can do so by clicking the "Delete branch" button.

delete-branch.JPG
You can always restore them by clicking the "Restore branch" button in your pull request.

restore-branch.JPG

โ“ How to resolve conflicts

conflict-github.JPG

It's common to encounter git conflicts in collaboration.
Conflicts usually occur when changes are on the same line(s), in the same file(s), from 2 different branches.
You will get notified about the conflicts when you create a pull request.

So, what should we do to resolve the conflicts?

You can do it directly on GitHub by clicking the "Resolve conflict" button.
But it would be better to resolve it in your local environment.

  • Navigate to your local main branch.
  • Pull the latest state of the remote main branch to your local main branch by running this command:
git pull
Enter fullscreen mode Exit fullscreen mode
  • Go to your working branch.
git checkout branch-name
Enter fullscreen mode Exit fullscreen mode
  • Merge your main branch into the working branch.
git merge branch-name main
Enter fullscreen mode Exit fullscreen mode
  • Fix the conflict.

git-conflict.JPG

Select one of the options of:
- Accept Current Change โ€” when you only want to keep the existing change.
- Accept Incoming Change โ€” when you only want to keep the newest change.
- Accept Both Changes โ€” when you want to keep both existing and newest changes.

Afterward, you can fix and adjust the codes manually if necessary.

  • After fixing the conflicts, add the changes for commit with git add .
  • Commit the changes. Don't forget to change the commit message example to your message.
  git commit -m "Merge the main branch into branch-name and resolve conflicts"
Enter fullscreen mode Exit fullscreen mode
  • Push the changes to the origin repo.
  git push origin branch-name
Enter fullscreen mode Exit fullscreen mode

โ“ How to write a pull request on GitHub (with examples in markdown)

  • Write a clear, descriptive title.
  # Create AddTodo component with some functionalities to add tasks to the list
Enter fullscreen mode Exit fullscreen mode
  • Include the link to the issue.
  ## Link Issue
  Closes #123
Enter fullscreen mode Exit fullscreen mode

By adding the word "Closes" before the link to the issue, the issue will automatically close whenever the pull request gets merged.

  • Include a clear description. Write down the changes that you made in this section.
  ## Description
  - Created an "AddTodo" component.
  - Added a form and the functionality to add tasks to the database.
Enter fullscreen mode Exit fullscreen mode
  • Mention the type of changes. Is the type of changes adding a new feature, fixing a bug, or others?
  ## Type of Changes
  โญ New feature
Enter fullscreen mode Exit fullscreen mode
  • Include screenshots, if any.
  • Include the steps to test the changes.
  ## Testing Steps
  - Run `npm start`.
  - After the page renders, navigate to the add task page by clicking the link on the homepage.
  - Enter a task.
  - Click submit button.
  - Go to the database. The submitted task should now be available and stored in the database.
Enter fullscreen mode Exit fullscreen mode

And that's it! ๐Ÿ™Œ
I hope you have a nice collaboration! ๐Ÿ˜„


Thank you for reading!
Last but not least, you can find me on Twitter. Let's connect! ๐Ÿ˜Š

Discussion (0)