How to fork an existing Meteorite package in a clean way?

Question

I'm trying to figure out the best/cleanest way to fork an existing package on Atmosphere within a project. I encountered a few occasions where an existing package needed some modifications and I was forced to fork it.

As far as I can tell, the following options exist. Unfortunately, all of these have their own issues and I have yet to find the perfect solution. I will use meteor-router as an example:

1. Simply copy the package files into your packages folder

Steps:

• remove packages/router/.git/
• edit packages/.gitignore and remove the 'router' line
• remove router from your smart.json
• add packages/router to your project repository and commit
• now make changes (this way your initial commit is a clean version and you can work out what you have changed yourself)

Advantages:

• easy to achieve and understand
• all the code you rely on can be found in your project repository

Disadvantages:

• you lose all the original repositories history
• it's hard to update to a newer version
• it's hard contribute your changes back to the original project

Do not even consider this for any but the simplest packages!

2. Fork on github, then ...

To fork a package on github, your can check your smart.lock file to see which repository is being used. Go to the github page of that repository and fork it.

Next, you have three options:

2a. Add it as a git submodule

More info on git submodules: http://git-scm.com/book/en/Git-Tools-Submodules

Steps:

• See the link above about how to init/create/update a submodule
• Remove the package from your smart.json

Advantages:

• Submodule versions are connected to your project
• Changes are immediately picked up

Disadvantages:

• All developers need to run git submodule init the first time and update to update
• You have to be aware of the issues with submodules when editing the checkout
• Read about other issues with submodules

2b. Edit your project's smart.json to use your version

Steps:

• In your smart.json, find "router": {} and add "git": "https://github.com/USER/meteor-router.git" inside the empty {}.
• Optionally, add a "branch" or "tag".

Advantages:

• You can still use Meteorite to manage your external packages
• Will work automatically for other developers and in deployment environments

Disadvantages:

• The code in your packages folder is not editable, as it's not a git repository
• Meteorite will not automatically update to the latest version every time your run it

(Suggested Meteorite improvement: allow packages to be installed in an editable form, like Python's pip allows using the '-e' parameter)

2c. Clone outside of your project and add a "path" to smart.json

Steps:

• Clone the package to a place outside of your project
• Similar to 2b, add a "path" to your smart.json to point Meteorite to your local checkout

Advantages:

• You can edit the package at will and Meteor will automatically pickup the changes.

Disadvantages:

• If you commit this smart.json, you will most likely break all other development/deployment environments...

---

Which method do you use? How do you work around the disadvantages to that method?

I might have missed some issues with these solutions.

Answer 1

For Meteor 1.0 I recommend the following:

1. Set up a local packages folder

   $ mkdir "$HOME/code/packages"
   

2. Add the PACKAGE_DIRS environment variable to your .bashrc/.zshrc file

   export PACKAGE_DIRS="$HOME/code/packages"
   

3. Fork and Clone the repository

   $ cd "$HOME/code/packages"
   $ git clone <yourGithubFork>
   

4. Install the package from your filesystem

   $ meteor add <packagenamespace>:<packagename>
   

Answer 2

There is an even easier answer than all of the above. Create a directory called packages in your project and put the package you want to override in it. Simple!

Ex: Let's say that you wanted to make some changes to accounts-ui-unstyled (which is a sub-dependency of accounts-ui) from meteor. Do a git clone of the entire meteor source to a local repository:

MyMachine:~ theuser$ cd Development/
MyMachine:Development theuser$ git clone https://github.com/meteor/meteor.git
MyMachine:Development theuser$ cp accounts-ui-unstyled ~/Development/MyProject/packages

In your project structure you would then have this

MyProject
 |
 -> client
 -> lib
 -> packages
    |
    -> accounts-ui-unstyled
 -> private
 -> public
 -> server
 -> tests

Any changes you make inside of MyProject/packages/accounts-ui-unstyled will now override the package.

Answer 3

2b. Edit your project's smart.json to use your version

I would recommend this version, as it is the most consistent with how the smart.json was intended to be used and supported. mrt update will correctly reflect the latest from the git repo I think.