A walk through GitHub

In this Article [link] I described why I think every developer should learn git and GitHub.

Many fresh graduates and juniors contacted me asking about guides on how they should deal with GitHub and how to interact.

Here, I will walk through some live examples and show my opinion about how good developer should deal with the open source community.

I'm assuming you know about git and GitHub.

Opening issues.

When you have a problem with a project, you submit a ticket (aka issue), you should clearly describe the issue and spend few seconds searching if it was reported before (If yes, go ahead and join the discussion).

Opening a ticket can be for:

• Asking for a feature.
• Asking how to contribute (If you want and the README file doesn't have enough information).
• Reporting a bug.
• Complaining about the leak of documentation.
• Complaining about the absence of some code quality tools.

This list isn't final and I'll add more if I got suggestions. generally, you got the idea, it's called an issue but I call it ticket because It's not only for issues, It's for discussions.

See this issue [link] as a good example. Here Bahaa cloned the repository and tried to play with it for some reason but couldn't log in. He decided to open an issue.

Bad examples are everywhere, you'll know them (some of them can be mine, but surely they are old).

Joining a discussion.

You decided to report a ticket, you found that someone was talking about it before.

Go through the discussion, if you found the answer there, good.
If not, do you have something to add? don't hesitate.

Something is not clear? ask for clarification (don't forget to mention the one you are talking to, it's good to quote the message you are replying to).

You see that there is no assignee and you can do it? don't submit a PR, ask first if the maintainers can assign it to you.
They will happily say yes in most cases, just give them a chance to look and see if they're missing something, avoid to make PR's that won't be merged (That is frustrating).

See this issue [link] as a good example, Here Mihai, Amr and Andrey participated in a discussion effectively.

Commits.

commit messages are important, how often you should commit? It's hard to tell.

Basically, make sure that what you did can be described in too few words (The commit message).

Are you working on an issue? Add its number in the commit message, this way the commit will be visible in the ticket's discussion.

This commit [link] could be a good example (Just had a typo which isn't a good thing).

This commit [link] is a good example.

This commit [link] is a bad example. why?

No reference to an issue, are your commits not related to any issues? probably that is a time wasting.

A bad message, 'update readme' isn't enough, could be added how to contribute section.

enough examples, you got the idea, right?

Pull Requests.

AKA PRs.

You submitted a PR? great, you're an active contributor.

Did you forget to describe what you did? To mention the issue that your PR is related to?

That is bad news, but not the worst for me.

Did you implement too many changes? Did you edit many files? all in one PR?

That is the worst, big PRs are hard to review and may cause a lot of trouble, whatever the issue you're solving or the feature you're adding, break it into smaller pieces and add todo comments for them.

This [link] and this [link] PRs are examples, can you tell what is good and what is bad?

You got me, bad PRs are hard to track and review, good PRs are not, and good PRs end merged with code base adding your name to the contributors' section.

Summary.

How to interact in GitHub is similar to how you interact in twitter or facebook, just different objectives and UX.

After some time you'll identify your set of good and bad things.

You also may choose to do a bad thing sometimes, it may not harm and save some time.

Hmm, try to avoid these moments, roles will make your GitHub life easier.