How to share your awesome PyRosetta and XML scripts with the Rosetta community

how_to_share_rosetta.md

How to share your awesome PyRosetta and XML scripts with the Rosetta community

Tutorial by Alex Carlin (carlin@ucdavis.edu)

So you've been developing some awesome Rosetta protocols using PyRosetta and XML, and you want to share them with the community. That's awesome! This tutorial will walk you through how to 1) clone the official repository, 2) add your scripts, 3) create a pull request letting the rest of the community know that your scripts are available to be merged in.

Before you start

Make sure you have git installed. You can check to see if it is installed by typing which git at the command line. If you don't have it installed, you can use sudo apt-get install git (Linux) or brew install git (macOS) to get a copy of this free software.

First, use git to clone the scripts repository

The first thing we will do is create a local copy of the community repository. To do this, you need to be a member of the RosettaCommons organization on GitHub (if you aren't yet, you can email your PI).

First, change into your documents directory, or wherever you would like to keep this repository. Then, use git to clone the repo and change into in. In this example, we will be adding a PyRosetta scripts. In order to add your XML scripts, clone the repo "rosetta_scripts_scripts" instead.

cd ~/Documents 
git clone git@github.com:RosettaCommons/pyrosetta_scripts.git
cd pyrosetta_scripts

Explore the structure of the repo

Now you can look around at the structure of the repo

$ tree -L 2 
.
├── apps
│   ├── __init__.py
│   ├── PeptideDesign
│   ├── ProteinIdealization
│   ├── README
│   ├── util
│   └── XMLtomover
├── benchmarks
│   └── README
├── doc
│   ├── lib
│   ├── README
│   └── tutorials
├── lib
├── README.md
├── tests
│   └── README
└── tools
    └── README

We will be putting our scripts into a new directory that we will create in the apps subdirectory.

Create a new branch for your work

Before we do anything, we need to create a personal tracked branch to keep track of the changes we make (this is called branching in git).

When you create a branch, it will be named like this: {user_name}/{branch_description}. Your {user_name} is the same as your GitHub username, and the {branch_description} can be anything you want.

In this case, I will be using rosalind as the Rosetta developer user name, and add_scripts as the description of the branch. You should substitute the user name for your own user name from here on out.

git checkout -b rosalind/add_scripts

git will respond with this message: Switched to a new branch 'rosalind/add_scripts'. Now, we can add our script.

Add your awesome script

The script I would like to add performs a single mutation. I am not sure if it fits into any of the existing directories, so I will create a new directory called PointMutations to hold scripts like this one (by convention, we are using camelcase for the names).

mkdir apps/PointMutations

My script is located at ~/Documents/AwesomeScripts/PointMutation.py, and the following commands will copy it into the repo into the folder I just created:

cp ~/Documents/AwesomeScripts/PointMutation.py apps/PointMutations/PointMutation.py

Add new files to git

Now, we would like git to become aware of this new file. To do this, we can use git add.

git add apps/PointMutations/PointMutation.py

A good check at this point is to run git status. You should see git recognize your new file as such:

On branch rosalind/add_scripts
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	new file:   apps/PointMutations/PointMutation.py

Commit your changes

Now that we have added the file. Let us commit it. To do this, you have two options, you can type git commit, and git will bring up your editor of choice. But since this is a simple commit, we can do this in one line with the following command.

git commit -m "Added my awesome script" 

Now you can run git status again, and you should see the following:

On branch rosalind/add_scripts
nothing to commit, working tree clean

Push your changes to GitHub

Now that we have copied our script in and added it to git, we can push our results back up to GitHub so that the community can see them.

git push

If you see an error message, git will provide you with the command to resolve it. In my case, I had to set my upstream branch explicity (this is for newer versions of git) using this command:

git push --set-upstream origin rosalind/add_scripts

Creating a pull request on GitHub

This part is a lot shorter. Navigate to https://github.com/RosettaCommons/pyrosetta_scripts (the home of our repo on GitHub). From there, find your branch in the pull-down tab at left (it's labeled "master", for the name of the main branch). Now, click the big green "Compare & Pull Request" button.

This creates a pull request: a public request to the other developers of the repo to merge your code in. In our community, the convention is that 2 independent developers must sign off (usually by leaving comments) before the pull request can be merged. The actual merge can be performed by you or someone else.