Developing Persephone

Workflow

  1. Pull the current development version from the master branch on Gitlab: https://git.idiv.de/xo30xoqa/persephone.

  2. If you are working on a new feature, create a new branch to avoid breaking the master branch. (The master branch should always be in a runnable and (as far as possible) error-free state.)

  3. Implement your changes.

  4. Run example.sh to make sure the model executes without crashing. Also run the test suite (cd test; julia runtests.jl).

  5. Commit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.

  6. Once your satisfied with your work, do another pull/merge from the master branch in case somebody else changed the branch in the meantime. Then merge your work into master and push to the Gitlab server.

  7. Repeat :-)

The Gitlab issue tracker can be used to create, discuss, and assign tasks, as well as to monitor progress towards milestones/releases. Once we have a first release, we will start using semantic versioning.

Agents.jl

Our model uses Agents.jl as a framework. Their repository can be used to inspect the source code or submit bug reports (the authors are quick to respond). Questions can be asked at the Julia Discourse forum.

Tutorial on collaborating on Julia packages: https://www.matecdev.com/posts/julia-package-collaboration.html.

Julia editors

Emacs

There are a couple of addons that make working with Julia much nicer in Emacs:

  1. julia-mode gives syntax highlighting. Install with M-x package-install julia-mode.

  2. julia-snail provides IDE-like features, especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer. Note that the installation can be somewhat tricky. You first need to manually install all the dependencies of its dependency vterm, then install vterm itself with M-x package-install vterm, before you can do M-x package-install julia-snail. Then add it to your init.el with (require 'julia-snail) and (add-hook 'julia-mode-hook #'julia-snail-mode).

  3. company-mode integrates with Snail to give code completion. Install with M-x package-install company, then add (add-hook 'julia-mode-hook #'company-mode) and (global-set-key (kbd "C-<tab>") 'company-complete) to your init.el.

  4. magit is a great git interface for Emacs. Install with M-x package-install magit and add (global-set-key (kbd "C-x g") 'magit-status) to your init.el.

VSCode

See here.

TODO: add more detail.

Other useful stuff

  1. Revise.jl allows one to reload code without restarting the Julia interpreter. Get it with Pkg.add("Revise"), then add using Revise to .julia/config/startup.jl to have it automatically available.

  2. git-bug is a commandline bug tracker that integrates directly with git. It can also be used as a local interface to Gitlab issues. To install on Linux, download the binary, copy it to /usr/local/bin/git-bug, and set it as executable with chmod +x /usr/local/bin/git-bug. To set up Gitlab integration, run git bug bridge configure from within the relevant repository.