Forking And Contributing To Open Source

What is Forking

Forking is basically having your own personal copy of a library that you can then hack on.

Forking on Github

To fork on Github is really easy, just find the library you want to fork and then press the fork button

Working on Your Fork

It's just a standard git repo and it has all the history in it up to the point you forked it.

You can create branches, make changes and generally work on it as normal.

Pulling Upstream Changes

Generally you will want to keep your fork up to date with the original version. To do this you need to add an extra git remote

git remote add upstream git@github.com:example/package.git

Then you can pull changes as you see fit

git checkout master
git pull upstream master

Pushing Upstream Changes to your Fork

After you have pulled the latest changes from upstream, you probably want to push everything to your fork to keep it up to date.

You can do this with:

git push origin '*:*'

Using Your Fork in Composer Projects

A common scenario is that one of your Composer dependencies is the thing you are working on, and you want to fix some niggles with it.

That means that you need to change your composer.json file to use your fork instead of the original. To do this we will use the VCS functionality of Composer repositories.

For example we want to have our own fork vmasciotta/magento2-owl-carousel.

You need click Fork button on the GitHub page and then add these changes to your project's composer.json. But before that on your fork you need to checkout to new branch which in this example is magento-2.2.2 branch.

"require": {
    "vmasciotta/magento2-owl-carousel":"dev-magento-2.2.2",
},
"repositories": {
    "owl-carousel": {
        "type": "vcs",
        "url": "https://github.com/edmondscommerce/magento2-owl-carousel"
    }
},

Execute composer update cd into vendor directory and confirm that the remote is your fork repository.

Making Composer Prefer Source

The best way to ensure that composer will always clone actual repos is to add the following to your composer.json file:

 "config": {
    "preferred-install": {
      "*": "source"
    }
  }

see the docs

Taking the Example of Working on Akeneo

So for example I want to work on Akeneo. I need to fork pim-community-dev at which point I get my fork.

Now I need to edit my Akeneo project composer.json to use my fork

{
  "require": {
    "akeneo/pim-community-dev": "~2.0.6"
  },
  "require-dev": {
    "doctrine/migrations": "1.5.0",
    "doctrine/doctrine-migrations-bundle": "1.2.1",
    "akeneo/pim-docs": "dev-master"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/edmondscommerce/pim-community-dev.git",
      "branch": "master"
    },
    {
      "type": "package",
      "package": {
        "name": "akeneo/pim-docs",
        "version": "master",
        "source": {
          "url": "https://github.com/akeneo/pim-docs.git",
          "type": "git",
          "reference": "master"
        }
      }
    }
  ],
  "config": {
    "preferred-install": {
      "*": "source"
    }
  }
}

Now I can run composer update and I should then have my own fork checked out in the vendor folder in place of the original.