11

I started to get more and more engaged in open source development and I was wondering if there are any guidelines on how to properly document and maintain a fork?

For example, let's say you fork a project to add some specific thing to it. Maybe you do not want to send pull requests back to the original project or maybe your addition is something that won't be merged back. Now you have your version of a project which is not really yours and you probably don't want to neither maintain it nor you really understand it.

But if the original project keeps growing, it would be nice to incorporate patches and new features. So, what do you do? Rebase all the time or merge changes continuously? How do you setup your branches: do you keep master branch which is always unmodified fork of the original with separate branch for your changes?

What about documentation? You most likely want to keep the original readme, since it describes the project rather well. But you also need to specify what your fork does differently or additionally. Maybe you need to remove references to automated build servers from the readme since they relate to the original project.

It is easy to fork and change the code, but that isn't good enough. I want to hear your opinions, experiences and recommendations in regards to the proper and healthy open source development.

Improve this question
1

2 Answers 2

Reset to default
5

I'm assuming you are referring to a project hosted on a DVCS services (e.g. GitHub) where forking and merging is the normal way of doing things ...

It is easy to fork and change the code, but that isn't good enough.

Good enough for what?

If you are doing this solely for your own benefit, then this is a no brainer. Do whatever you like. But do it quietly so that you don't detract from the project that you forked from.

If you are doing this for other people's benefit then, forking and changing when you have no intention of merging is probably a bad thing:

  • You will inevitably antagonize the people working on the original project.

  • You are creating a situation where the developer effort is inevitably spread more thinly. It is inefficient.

  • You are creating uncertainty and confusion for users. Which version should they use? Who should they trust to keep working on their fork? To do things properly?

Unless you have a really, really good reason to maintain a long-term public fork, you should always aim to merge back. And in order for your pull requests to be accepted you should follow the project's written guidelines for contributions. If there are no guidelines, treat the best parts of the existing codebase as an example. (If there is documentation, add / update it. If there are unit tests, include unit tests for your changes.) If nothing else, doing these things will make it more likely that your pull requests that will be accepted.

Another strategy for getting your pull requests accepted is to discuss what you are intending to do with the lead developer, and talk through any issues ... before you start coding. And listen to what he / she says. Be polite, be deferential, be patient. Don't be a prima donna.

I asked about how to maintain healthy project fork which doesn't look dead and has proper documentation that states what its intent is.

Well my first advice would be DON'T ... unless you have good reason. Long term public forks are unhealthy, for the reasons above.

Apart from that, maintaining a healthy fork is the same as a maintaining a healthy project. For example, write the documentation, maintain the activity, provide support, recruit other contributors ... have a purpose and plan.

Improve this answer
1
  • I know that maintaining it in the long run might be taxing. It depends in which direction you wish to take your project to. I think that contacting the original owner is the best way. Unless, of course, if he or she is no longer interested in developing the project.
    – Toni Petrina
    Apr 1, 2013 at 8:18
4

Maybe you do not want to send pull requests back to the original project or maybe your addition is something that won't be merged back

Then that's it.

Why would you be concerned about incorporating your changes into the original project if you aren't concerned about merging or pulling? Save that for the serious folks. This is especially true if you have no intention of redistributing your fork, or only intend to distribute it within your organization.

In short, be a serious contributor, or don't.

If you are serious about being a contributor, the best way to approach that is to contact the project owner. Generally, they will allow you to make pull requests when you have demonstrated that you're trustworthy by contributing useful changes. The project owner can tell you what they expect in terms of proper documentation, release schedules and the like.

Improve this answer
3
  • 1
    This is completely off the mark. I asked about how to maintain healthy project fork which doesn't look dead and has proper documentation that states what its intent is.
    – Toni Petrina
    Apr 1, 2013 at 0:04
  • It all comes down to how interested you are in your changes being available to the public. If you're only going to use the changes in-house, don't worry about any of this. If you want to incorporate the changes into the main branch, the project owner is the one with all the information; there's no secret handshake or universally established protocol. If you want to fork it, and publish the fork yourself, you get to make the rules and decide how you're going to accept changes to your branch.
    – Robert Harvey
    Apr 1, 2013 at 0:07
  • Unless, of course, I've completely misunderstood your question. What is the netiquette? Be polite, respectful, and don't do stupid shit. Make sure you're abiding by the terms of their license. Read their documentation; sometimes they will state exactly how they expect others to interact with the project.
    – Robert Harvey
    Apr 1, 2013 at 0:08

Not the answer you're looking for? Browse other questions tagged or ask your own question.