Developing Persefone
Workflow
Pull the current version from the master branch on Gitlab: https://git.idiv.de/xo30xoqa/persephone.
If you are working on a new feature, create a new branch to avoid breaking the
master
branch. (Themaster
branch on Github should always be in a runnable and error-free state.)Implement your changes.
Run an example simulation and the test suite to make sure everything works without crashing (
make run
andmake test
on Linux, or executerun.jl
andtest/runtests.jl
manually.)Commit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.
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 intomaster
and push to the Gitlab server.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.
Libraries
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.
Revise.jl
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.
Test
Persefone uses the inbuilt Julia testing framework. All new functions should have appropriate tests written for them in the appropriate file in the test
directory. (See test/runtests.jl
for details.) There are three ways to run the test suite: in the terminal, executing make test
or cd test; julia runtests.jl
; or in the Julia REPL, Pkg.activate("."); Pkg.test()
.
Documenter.jl
The HTML documentation is generated using Documenter.jl. Therefore, all new functions should have docstrings attached. New files need to be integrated into the relevant documentation source files in docs/src
, and if necessary into docs/builddocs.jl
. To build the documentation, run make docs
, or cd docs; julia builddocs.jl
(if using the latter, don't forget to update the date and commit in docs/src/index.md
).
Julia editors
Emacs
There are a couple of addons that make working with Julia much nicer in Emacs:
julia-mode
gives syntax highlighting. Install withM-x package-install julia-mode
.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 withM-x package-install vterm
, before you can doM-x package-install julia-snail
. Then add it to yourinit.el
with(require 'julia-snail)
and(add-hook 'julia-mode-hook #'julia-snail-mode)
.company-mode
integrates with Snail to give code completion. Install withM-x package-install company
, then add(add-hook 'julia-mode-hook #'company-mode)
and(global-set-key (kbd "C-<tab>") 'company-complete)
to yourinit.el
.magit
is a great git interface for Emacs. Install withM-x package-install magit
and add(global-set-key (kbd "C-x g") 'magit-status)
to yourinit.el
.
VSCode
See here.
TODO: add more detail.