DEV Community: Oleksiy Rudenko

An intro to contributing to a 3rd party repo for beginners

Oleksiy Rudenko — Thu, 22 Nov 2018 15:00:09 +0000

An opinionated and probably oversimplified guidelines. Please, feel free challenging in comments.

You will find visualized what's this article is above in Google Slides.

Pre-requisites

You know and use basic git commands like init, clone, add, commit, branch, checkout, merge, pull, push.

You probably know and use git commands like fetch, pull --rebase, rebase, cherry-pick.

You want to contribute to a repo you do not have write access to.

You do not know how to or do not feel confident working with repos you do not have write access to.

You do not follow any firm workflow working with your own repos or repos you do not have write access to.

What you will learn

How to keep your fork in sync with a source repo
How to minimize risks of conflicts
How to keep your repo history tree as clean as possible
How to contribute properly via pull requests

A good workflow to start with

Some definitions:

upstream is a repo you want to contribute to
origin or fork is your own fork of an upstream
local is a local clone of origin

Initialize things

Fork an upstream. On GitHub navigate to the upstream and click Fork button.
git clone origin-url.git target-directory on your machine to clone your fork
cd target-directory
git remote add upstream-url.git to enable upstream-related actions

Add your changes

It is important to have your fork in sync with upstream, employ branches and follow certain workflow to minimize conflicts risks and keep the history tree as clean as possible.

Initialize a feature branch

sync local and origin with upstream git checkout master && git pull upstream master && git push origin master
create a feature branch with a meaningful name git checkout -b feature-branch

There are many branch naming conventions. Few to mention are:

start with author initials so other collaborators know who initialized the branch and also find branches per author, e.g. or-feature-portview

use slashes to denominate scopes, e.g. feature/api/rest, bugfix/sleep

use ticket/issue/epic/story id, e.g. feat/epic123/story128/search-people

Useful alias:

git config --global alias.sync-master '!git checkout master && git pull upstream master && git push origin master'

Usage: git sync-master

Feature development cycle

do whatever you want
commit often: git add . && git commit -m "Add REST api PATCH method"
squash eventually grouping commits as appropriate: git rebase -i <REF> (Making use of git rebase)
sync eventually local, origin, and feature branch with upstream
- git checkout master && git pull upstream master && git push origin master
- git checkout - && git merge master
- resolve conflicts using your IDE or command line
- when done git add . && gir commit -m "Resolved merge conflict by incorporating both suggestions"
- see also Resolving a merge conflict using the command line
go to #1
eventually push to origin: git push origin feature-branch

Useful alias:

git config --global alias.sync-branch '!git sync-master && git checkout - && git merge master'

Usage: git sync-branch (it also does sync-master as a part of the flow)

Commit message

There are numbers of commit message structure conventions.
To mention a few:

start with commit scope, e.g. one of feat|fix|docs|style|refactor|test|chore
add feature/fix scope, e.g. (api)
use imperative mood in the subject line, e.g. one of Add|Change|Fix|Refactor|Remove|Bump version|Release version

If you resolve an issue (in upstream or fork) it is useful to have a note on issue resolution.

Your commit message may look like the following

fix(foo api): Fix ABC component render conditions

Resolves: #12
See also: #34, #78

Contribute via pull request

Contributing is not necessarily required. You may develop your fork for your own purposes (adhering to upstream license conditions).

Otherwise stick to the following contribution workflow:

git push origin feature-branch to push your feature branch to the origin.
Navigate to the cloud git hub (e.g. GitHub)
Use cloud UI to create the PR
Pass through code review process until your changes are merged or declined

Once your feature branch gets merged you will find your commits in upon next sync with upstream. So, you don't need merging those to your master locally.

However, you will need to merge into master if you do not contribute to the upstream or your PR is declined and you want to keep those for yourself.

Cleaning up

Once your PR approved and merged you can get rid off your feature branch.

git branch -D feature-branch

Feel free forking the source gist and editing it so it fits your particular needs (e.g. remove parts that you already know well).

Please, do not pollute project's .gitignore

Oleksiy Rudenko — Thu, 08 Nov 2018 20:08:46 +0000

.gitignore is a rule-set defining resources we do not want to be git tracked, or putting it other way be ignored by git.

Spoiler alert. If you know what is ~/.gitignore about, you don't need to read any further.

There are 3 most common major groups of resources that we do not want or just do not need to track with git:

sources compiled/transpiled into intermediary code files (e.g. .obj or .o in C/C++ universe), distribution packages, other deliverables, logs etc. whatever derives from tracked source code.
dev environment temporary files and/or e.g. IDE settings specific to the project (yet very specific to a particular IDE)
scratches, notes, clipboards etc.

You don't need to track derivatives from item 1 since you can build deliverables at any time from sources and having those under VCS control is senseless. So these exclusions are pretty helpful and every project contributor would benefit from having them listed in project's .gitignore.

Next you will add your favourite IDE temps to .gitignore, your colleagues will add theirs, and someone else may wonder one day if .DS_store/ is anything to do with project's database or why idea sharing is not encouraged on the project (.idea/).

Project contributors may also agree on that scratches and notes are stored under tmp/ and should not be shared via git remote.

OK.

There are many collections and helpful resources that would assist you in compiling a .gitignore that covers your technology stack (item 1), most common IDEs (item 2), and also smth like tmp/ to cover item 3.

To name a few:

But why do you want to have even a hint of anything not related to the project in your project files? IDEs come and go. Personal notes? Too personal.

Project .gitignore becomes polluted. Rules to cover item 1 are OK as those bring value to the project contribution team.

Imagine (really easy do) you contribute to an open source project where .gitignore doesn't list your fav IDE exclusion rule. There are two options to resolve the situation:

Add a rule to exclude your favourite yet not hypy IDE to project's .gitignore
Do something like git add -A && git reset -- MyLovelyIDE/* at every commit

Both are neither good, nor convenient.

There is a proper place to keep your individual preferences out of git track and not confusing your project mates.

Global .gitignore

Create a .gitignore file in your home directory ~/ (C:\Users\your-user-name\ under Windows).
Populate it with exclusion rules you would have in any project (dev environment and IDE settings, subdirectories for notes and scratches etc.)
run git config --global core.excludesfile ~/.gitignore

You are done! Share your discovery with colleagues.

Cover image credits: timbercode.pl

Git backed package management

Oleksiy Rudenko — Wed, 31 Oct 2018 13:06:12 +0000

As a developer I want to keep my code base DRY and also DRO¹ as much as only possible. To achieve that I want to be able to

import a 3rd-party package
update imported package from its source

There are package and dependency managers that come to rescue. npm and yarn in JavaScript Universe, and Composer often attributed to PHP World to name a few.

But what if your technology stack ecosystem doesn't offer any (BTW, did you know you can effectively use either of the above in virtually any ecosystem?) or only tools you can (or may) employ are Ctrl-C/Ctrl-V² and/or git?

Copy-pasting is the latest resort. Let's stick to git.

Many employ the following git-based tools:

git-submodule
git subtree merge strategy
git-subtree (comes bundled with git since release 1.7.11)
The coolest merge EVER!

Well, the above works. But recently I found a tool that not only removes hassle but also allows to push changes to imported packages back to source (consider pull-request mechanism though).

Here is the hero of the day!

git-subrepo

Basic workflow is as simple as

# init
git subrepo clone anotherRepo.git localSubdir4anotherRepo -b master
# update from anotherRepo
git subrepo pull localSubdir4anotherRepo
# export back
git subrepo push localSubdir4anotherRepo -b anotherRepo-target-branch

I just love it.

More details and further reading on the topic available in Repo import and export back gist.

⁽¹⁾ - Don't Repeat Others; arguable but IMO perfectly fits the context here.

⁽²⁾ - or equivalent supporting content copy-pasting.