Submission workflow

The changes needed for a submission to the library are pretty straightforward - we just need an archive file with the extension and its dependencies along with a change to the libraries.conf file. But the actual process of making the pull request can be a little tricky, especially if you aren't used to git. Below is a quick suggested outline to help get through an extension submission with a minimum of problems.

Requirements

You'll need to have: git installed, a GitHub account, a network connection, an extension to share, a good code-aware text editor, and a command terminal to run the git commands at.

First Steps

First, create your own fork of the NetLogo-Libaries repository. GitHub has some directions for forking, but it's just a matter of hitting the Fork button on the landing page of the repository.

Next you'll need to clone a local copy of your forked version of the library. Open up your terminal.

git clone https://github.com/$YOUR_USERNAME/NetLogo-Libraries.git

This will copy your fork into a folder called NetLogo-Libraries in whatever directory you run the command in.

After that, we want to set an upstream remote repository. When you clone, git will remember an origin, the remote repository you cloned from. In this case that's your forked version. We also are probably going to want to update with changes to the NetLogo organizations version as well, which we'll call upstream.

git remote add upstream https://github.com/NetLogo/NetLogo-Libraries.git

This tells git about the NetLogo org's version of the repository.

git remote -v

Look at the remotes that are registered with git to confirm we have what we expect. You should have yours listed as origin and NetLogo's as upstream.

Extension Submission or Update

First, checkout a new branch for your submission/update. We do not recommend working on the 6.1 branch, since it gets frequent updates and you can wind up in a conflicted state if yours is stale. Note that in this document 6.1 refers to the current NetLogo API version, not the current released desktop NetLogo version. It's easier to keep your work on a separate branch so you can more easily update for future submissions.

git checkout -b my-extension-1.1.1

This creates a new branch with the name my-extension-1.1.1 and checks it out as active so we can work on it without disturbing the 6.1 branch.

Next, create and add your extension zip file. It's critical to not add a folder with your extension to the zip file, but rather add the individual files directly. NetLogo won't be able to tell where your extension is if it's in a folder inside the zip.

# No good, folder in the zip file:
my-extension-1.0.0.zip
  └──my-extension-1.0.0/
       └──my-extension.jar


# Good, will work:
my-extension-1.0.0.zip
  └──my-extension.jar

Next, update the libraries.conf per the directions in the README.md. It's best to use a good code-aware text editor for this, as general text editors (like Notepad on Windows or TextEdit on macOS) might munge the file a bit by adding smart-quotes or strange spaces.

Once you've got your changes ready, you can commit and push them to your repository.

# Check the changes pending are just the zip file and the `libraries.conf` file
git status

# Check the libraries.conf changes look valid
git diff

# Add the two changes to staging for a commit
git add --all

# Commit
git commit -m "Add my-extension 1.0.0"

# Push your change to your GitHub repository
git push origin my-extension-1.0.0

And that's it, you can head back to GitHub in a web browser and open your pull request for your branch.

Future Submissions/Updates

If you come back for another extensions submission or update, you'll want to first update your 6.1 branch from upstream.

git checkout 6.1
git fetch upstream
git reset --hard upstream/6.1
git push origin 6.1

These commands checkout the 6.1 branch, gets the latest information from the NetLogo organization's upstream repository, resets the local branch to the latest from upstream, then pushes those changes to your GitHub 6.1 branch, just for reference.

After those steps are complete, you are ready to checkout a new branch for your extension submission or update, as above!