GitHub

Part 2: GitHub 🚀

Step 0 - Project initialization

Create a repository and commit the files & folders contained in the calculator folder. Some steps should be completed in groups of at least 2. Go to your repository settings, and in the Collaborators add your teammate!

Pro tips:

Don't forget to use the commit norm you learned in the previous part 😉

Don't forget to use branches! This time, try to create it directly in GitHub 🚀

This workshop is based on PoC Innovation's Open-Source project template.
Several links to specific parts of the getting started guide will be given to you, but don't spend too much time on it, we have a lot to cover! You can read it entirely later.

Step 1 - Issues & Pull Requests (PRs)

📑 Description:

On a project, you'll need a tool to track and organize your work: with GitHub Issues, you can track feature requests, user feedbacks and bug reports.
Contributions can also be managed with Pull Requests to review code and discuss about it before merging on another branch.
If you played a bit with the calculator you may notice the given result isn't correct.

📌 Tasks:

You have to create 3 issues:

• One to describe the problem, with expected behavior and what you are experiencing.
• Another to suggest a feature (add all the arguments instead of just the first 2)
• A last one to take a single string as parameter and support operators in it (this one will not be implemented)

Then you have to create two branches (fix/wrong-result and feat/multi-arguments) and solve the related issues on it.
Create a Pull Request for each branch and use 2 different methods to link the related issues. When it's done, add your teammate as reviewer and play with the review tool in the Files Changed tab!

📚 Documentation:

• Classification with labels
• Assignment
• Closing keywords

Instead of organizing the content manually, you can use templates for issues and PRs. It's really useful to let contributors know what information maintainers need and keep a common structure between contributions.
You can find some great examples for different types of issues in our Open-Source project template as long as one for Pull Requests.

Several options are available when merging a PR. Here's a Comparison of Merging Strategies in GitHub filled with information to let you choose according to your needs.

✔️ Validation:

Try to make it as complete as possible, then take a look at the expected results:

Problem issue

Feature issue

Not implemented issue

Problem PR

Feature PR

PR review example

Step 2 - Projects & Milestones

📑 Description:

You can manage features and tasks with issues, group commits and do code reviews with PRs, but how do you actually organize your work in tables like well-known ticketing tools? That's where GitHub Projects come into play!
But how to you handle deadlines and group several issues and PRs linked to a sprint for example ? Milestones are exactly what you need for this!
You can find them in the Issues tab.

📌 Tasks:

Create a project named Calculator with 3 columns (by default To do, In progress and Done but you can rename it) with automation to add issues in To do when they are created, move created PRs to In progress and fill the Done column when closing issues or merging PRs.
Then, you can play with milestones by creating one with a due date of January 19, 2038 and adding Issues to it.

There is no milestone template, but nothing prevents you from having one in the .github folder and paste it's content when you create a milestone. Here's an example of what it could look like 🚀

✔️ Validation:

You can test it by creating other issues:

Creating an issue

Closing an issue

Project view example

Milestone example

A new GitHub Project experience is currently in public beta. We chose not to cover it because it's subject to major changes, but it brings great features such as custom fields and different views.

Step 3 - Actions

📑 Description:

Keeping your code clean and making sure it still works as intended when you develop new features is very important, and GitHub provides you a useful tool for this: Actions !
Whether you want to build, test or deploy your code, you can create custom workflows triggered by any GitHub event (push, pull_request, new issue...)

📌 Tasks:

Follow this quickstart to create your first action !

✔️ Validation:

You can see your workflow runs in the Action tab of your repository

Action tab preview

If you want to learn more about GitHub Actions with real use cases, you can check our dedicated workshop!

Step 4 - Branches protection settings

📑 Description:

Branch protection rules are a great way to enforce good practices.
For example, your production branch (usually main) should be as clean and bug-free as possible, so you don't want to push directly on it and if you have CI tests with GitHub Actions it's a good practice to ensure they all passed when merging on main.
Even if your collaborators and yourself know this, a mistake or a malicious act may occur and enforcing these practices isn't a bad idea.

📌 Tasks:

Go to Settings -> Code and automation -> Branches and add rules to protect your main and dev branches.

Take a look at the protection settings we recommend for main and don't hesitate to ask if you have any question about it 😉

To go further

You've learned how to use a lot of tools provided by GitHub, but there's a lot more to discover !

• The GitHub Learning Lab provides some great hands-on courses to grow your skills!
• Making open-source contributions is a great way to apply what you've learned in a real project.
  Pay attention to good first issue labels directly on GitHub or on dedicated sites.

Author

Reza Rahemtola

Organization

🚀 Don't hesitate to follow us on our different networks, and put a star 🌟 on PoC's repositories.