For developers interested in expanding pymatgen for their own purposes, we recommend forking pymatgen directly from the pymatgen GitHub repo. Here’s a typical workflow (adapted from http://www.eqqon.com/index.php/Collaborative_Github_Workflow):
Ignore the Github fork queue. Let the maintainer of pymatgen worry about the fork queue.
Create a free GitHub account (if you don’t already have one) and perform the necessary setup (e.g., install SSH keys etc.).
Fork the pymatgen GitHub repo, i.e., go to the main pymatgen GitHub repo and click fork to create a copy of the pymatgen code base on your own Github account.
Install git on your local machine (if you don’t already have it).
Clone your forked repo to your local machine. You will work mostly with your local repo and only publish changes when they are ready to be merged:
git clone firstname.lastname@example.org:YOURNAME/pymatgen.git
Note that the entire Github repo is fairly large because of the presence of test files, but these are absolutely necessary for rigorous testing of the code.
It is highly recommended you install all the optional dependencies as well.
Code (see Coding Guidelines). Commit early and commit often. Keep your code up to date. You need to add the main repository to the list of your remotes. Let’s name the upstream repo as mpmaster (materialsproject master).
git remote add mpmaster git://github.com/materialsproject/pymatgen.git
Make sure your repository is clean (no uncommitted changes) and is currently on the master branch. If not, commit or stash any changes and switch to the master.
git checkout master
Then you can pull all the new commits from the main line
git pull mpmaster master
Remember, pull is a combination of the commands fetch and merge, so there may be merge conflicts to be manually resolved.
Publish your contributions. Assuming that you now have a couple of commits that you would like to contribute to the main repository. Please follow the following steps:
If your change is based on a relatively old state of the main repository, then you should probably bring your repository up-to-date first to see if the change is not creating any merge conflicts.
Check that everything compiles cleanly and passes all tests. The pymatgen repo comes with a complete set of tests for all modules. If you have written new modules or methods, you must write tests for the new code as well (see Coding Guidelines). Install and run nosetest in your local repo directory and fix all errors before continuing further. There must be no errors for the nosetest.
If everything is ok, publish the commits to your github repository.
git push origin master
Now that your commit is published, it doesn’t mean that it has already been merged into the main repository. You should issue a merge request to pymatgen’ maintainers. They will pull your commits and run their own tests before releasing.
Given that pymatgen is intended to be long-term code base, we adopt very strict quality control and coding guidelines for all contributions to pymatgen. The following must be satisfied for your contributions to be accepted into pymatgen.
For the above, if in doubt, please refer to the core classes in pymatgen for examples of what is expected.