git-course

Kottans-Frontend MIT Licensed Entry level: beginner

Git workflow and GitHub

This module looks big. Actually it is more about concepts and tasks per se are tiny.

Table of Contents

A. Why mastering this?

Git is not only about storing versioned code but is also about communication. There are some communication patterns to follow that will make interaction with your peers and superiors easier and better structured, i.e. more efficient.

The collaboration flow highlighted in this module comprises:

B. Intro to problem solving

A problem solving workflow, in general, comprises:

  1. Problem identification
  2. Solution suggestion
  3. Solution alignment and approval
  4. Putting solution into life

In software development the above maps as follows:

B1. Problem identification

A problem can be e.g.:

When a problem is identified it should be reported as an issue in relevant repo context.

Issue details can contain Steps to Reproduce and environment details (bug), suggestions on the solution (feature or improvement request).

B2. Solution suggestion

Once a problem is documented as an issue it can be assigned to someone. Issue reporter can assign himself or herself, or a team lead can assign the issue to someone from the team.

Solution suggestion itself is a commit of code (or text) that solves the problem (normally in a feature branch) submitted with a Pull Request (Merge Rerquest in other cloud VCS).

B3. Solution alignment and approval

Solution alignment is a process where stakeholders or peers, or supervisors have an opportunity to conduct code review (cross-check the solution for correctness or safety, or ability to achieve the solution goal).

Depending on conventions in a team, a Pull Request author may assign a team lead or peers to review the PR. Alternatively peers may assign themselves to review the PR as per their capacity. The team lead may re-assign the PR to someone else.

Changes can be requested in the course of the Pull Request review.

Solution approval is a process where key stakeholders or decision makers confirm that the solution is appropriate.

Normally, review from at least two peers is required. This also depends on the team conventions.

B4. Putting solution into life

Putting solution into life means it becomes a part of the code base by merging into (or rebasing onto) master or other production streamline branch.

This is normally done by one of reviewers or by a team lead once there are no non-resolved change requests and required number of approvals (e.g. two) are obtained.

C. Targets

GitHub offers Issues and Pull Request mechanics.

Skills to earn, improve or refresh:

To feel safe we shall play around with text. Actually, MarkDown is a type of code, just like HTML, as it gets interpreted to render a nice document view.

D. Learn and Do

D1. Issues

Note that it is good to start an issue title with a proper verb (like we do for commits):

Just imagine that someone fixing the issue will create a commit with the very same message at your issue title. It will establish a strong binding between the issue and commit that resolves it.

Read

Do

Option 1. You might have noted something not so easy to master or comprehend in the past modules. This might be a good source of an idea to create an issue on. Let’s take this as a need for improvement.

Option 2. The course materials may contain a broken link, a typo in the text, something like http://domain.com/a-very-long-url instead of nicely formatted link. Let’s take this for a bug.

Option 3. Course is really a Work In Progress and misses many modules to be populated with educational content. Let’s take this as a lack of a feature.

Option 4. Any other bug, need of improvement or lack of a feature.

Cannot invent a problem? No problem. Check this document full of typos. Or just ask your peers for support and ideas.

Simple issues (like typos) can be resolved with a single commit and without a discussion. But let’s learn on a simple case to be ready for more complicated ones.

The task is to

Check this issue #1 for example.

And remember, MarkDown is here to make your issue description easier to read.

D2. Discussion

Do

Check this issue #1 for an example.

You’re done.

D3. Forking

You make a fork of a repo when you

What is nice with forks is that you can create a Pull Request into original repo from your fork’s branch!

NB! Cloning a repo and just pushing it up to your space doesn’t create a fork binding and will not enable cross-repositorial pull requests.

Read

Do

Fork a repo practice

You need this skill in order to complete the following task.

D4. Pull request

Pull request is a device to propose code changes (consider .md file is some code as well, like HTML), have a spare pair of eyes to look at (doing a code review), and approve a good solution.

Read

Do

You may not assign reviewers if you’re not an owner of the repo or not a part of organization. Try identifying the owner or repo collaborators and mention them in a comment by their names. If unable to identify relevant persons then just skip this step.

Alternative

Send a pull-request to Kottans/mock-repo proposing a change. It could be anything, really. If you have found a typo in README.md - great! Take care to give your PR a meaningful name and description. Please, do not suggest changes via GitHub Web UI, the target is to emulate code contribution flow using branch-commit-push techniques.

Please note, that your PR may not be reviewed quickly.

Something went wrong?

Seek for the help among your peers (e.g. in a chat). Also you may find this guide helpful when facing irrelevant commits problem.

Pull Requests are contributions. Many projects contain contribution guidelines, many guidelines are quite applicable across projects. Whenever you see CONTRIBUTING.md it is worth reading before you start contribution to a project.

You may find something useful or interesting in other projects’ contribution guidelines. Check this example 1, and this example 2.

D5. Code review

It is a good practice to conduct a code review to make sure a PR introduces useful, bugless :smirk: code.

By convention, approvals from two code reviewers is required to approve a PR.

Code review can be as short as LGTM (Looks Good To Me) with an approval or a series of comments to the code with a Change Request.

Read

Do

D6. Code conflict resolution

At any stage of PR the author may face a code conflict. GitHub will warn you. This section is intended to make you well prepared. No panics!

Read

NB! Resolving a conflict using command line is a preferred method in many cases.

Do

D7. Approve and Merge Pull Request

Once a PR is approved (e.g. by 2 code reviewers) the code proposal can be merged into master.

Read

About merge methods on GitHub

Do

GitHub offers three merging strategies:

Opt for squash or rebase as these keep the git history linear.

You are done!

What if a PR should be closed without merge?

If you decide just to close a PR, i.e. reject it or cancel, you can do it with Close pull request button.

It is important to give a reason for your peers and future yourself. Reason shouldn’t be extensive, just a couple of clear words. Check this out for example.

D8. Draft pull request

Draft Pull Requests are the same as normal Pull Requests. The only difference is that a draft Pull Request cannot be merged into the repo codebase until it is finalized and ready to become a real code proposal.

Draft Pull Requests are good to open discussion on incomplete code, e.g. when you get stuck and need help or an advice.

Read

Introducing Draft Pull Requests

E. When completed

You did a lot and greatly improved your git and collaboration skills!

When done let others know you have passed this module.

This lets other know your progress and probably someone will ask you for some help in this module.

Where to communicate? In a chat you come here from :)

Now you are ready to efficiently collaborate with your teammates in a real project and contribute to Open Source Projects. Tell others that you are eager to get involved into any.

:gift: On GitHub you get subscribed for notifications when e.g. a new repo is created in your organization. You can unsubscribe from notifications on selected repos here or even from a particular organization. This would help to see only notifications you want.

Meanwhile you may want to become a Git Ninja.

F. Extras

F1. Gist

Gist is a tiny repo, and normally used to keep simple, often single file code snippets or docs, that do not deserve to be a project and need no much collaboration via e.g. Pull Requests.

Read

Do

When completed

Proceed to Git workshop

Course contents

This site is open source. Improve this page.