Here at Liip we obviously try to reuse all the good stuff in the Symfony2 and PHP community. So instead of reinventing the wheel when we find that a feature is missing we just fork, patch and submit our changes upstream. So far so simple.

The problem is of course that this entire process takes time during which our projects need to move on. As a result there is a time period where most likely our project will need to use the fork. I must say I am still not entirely happy with the workflow I am going to describe here. So it is definitely still a work in progress and needs refinement and we are only partially using the below described approach. Hopefully feedback to this post will get us to a perfected approach.

  1. fork the project

Make sure to fork to an organization that co-workers can reach. Usually we fork to the Liip organization. If we have client developers on the team we fork to the clients organization.

  1. update the description of the fork

Make sure to declare this fork as transient, so that nobody gets the idea that this fork will stick around. Github's repo description can be modified without changing anything in the repository.

  1. create a feature branch with your changes

Committing to master would seriously break the workflow. Never assume you will only need one feature changed and mixing features will make it harder to get your features merged upstream. Never assume that upstream will accept your patch, they might go with someone else's patch. Never assume that your PR actually makes sense, sometimes after submitting your PR you realize that it was actually a bad idea and you should have taken a different approach.

  1. create a ticket on your fork for the branch

This ties in with 2). Anyone using this branch should subscribe to that ticket. The ticket should also reference the PR. This way it is later easily possible to alert anyone that cares that the PR has been merged upstream and that you are going to remove the branch in X number of days.

  1. submit a PR

  2. update your project to point to your feature branch

At this point you need to make sure that all relevant people from your project are subscribed to the branch ticket.

  1. once the PR is merged switch point your project back to the original repo

  2. update the branch ticket that you are about to remove the branch in X number of days

  3. remove the feature branch

  4. if there are no more feature branches, remove the repo

Since nobody should depend on your master it should be safe to remove the repo once all feature branches are removed.

Note in some cases you might need multiple features at once. In that case create a separate feature branch for each feature and create another feature branch that combines all the features you need.

Also its best to make sure that upstream addresses your PR in a timely manner. Otherwise more and more people will start relying on your fork, you start to forget what it was about and more importantly, you might become incompatible with upstream. Making sure that your PR has a good description, tests and documentation will go a long way to getting your PR merged sooner rather than later. A friendly nudge now and then can also help to get things back on the radar ( nudge Kris nudge nudge).

If all else fails and you are unhappy with the way upstream handles the merging or you want to take things into a different direction, do a for ā€œrealā€ fork. At this point you can start merging into master, but be aware that getting upstream features will now become potentially messy. So far we have only done this in one case where we forked the AvalancheImagineBundle to the LiipImagineBundle since we need additional flexibility that Bulat didn't want to add to his bundle.