Developer documentation

If you want to make contributions to this package that involves code, then this guide is for you.

First time clone

If this is the first time you work with this repository, follow the instructions below to clone the repository.

1. Fork this repo

2. Clone your repo (this will create a git remote called origin)

3. Add this repo as a remote:

   git remote add upstream https://github.com/rsenne/ParallelMCMC.jl

This will ensure that you have two remotes in your git: origin and upstream. You will create branches and push to origin, and you will fetch and update your local main branch from upstream.

Linting and formatting

Install a plugin on your editor to use EditorConfig. This will ensure that your editor is configured with important formatting settings.

We use https://pre-commit.com to run the linters and formatters. In particular, the Julia code is formatted using JuliaFormatter.jl, so please install it globally first:

julia> # Press ]
pkg> activate
pkg> add JuliaFormatter

To install pre-commit, we recommend using pipx as follows:

# Install pipx following the link
pipx install pre-commit

With pre-commit installed, activate it as a pre-commit hook:

pre-commit install

To run the linting and formatting manually, enter the command below:

pre-commit run -a

Now, you can only commit if all the pre-commit tests pass.

Link checking locally

We use lychee for link checking in CI. You can run it locally to avoid waiting for CI. First, install lychee, then run against the repository root using the project config:

lychee --no-progress --config lychee.toml .

Testing

As with most Julia packages, you can just open Julia in the repository folder, activate the environment, and run test:

julia> # press ]
pkg> activate .
pkg> test

Working on a new issue

We try to keep a linear history in this repo, so it is important to keep your branches up-to-date.

1. Fetch from the remote and fast-forward your local main

   git fetch upstream
   git switch main
   git merge --ff-only upstream/main

2. Branch from main to address the issue (see below for naming)

   git switch -c 42-add-answer-universe

3. Push the new local branch to your personal remote repository

   git push -u origin 42-add-answer-universe

4. Create a pull request to merge your remote branch into the org main.

Branch naming

• If there is an associated issue, add the issue number.
• If there is no associated issue, and the changes are small, add a prefix such as "typo", "hotfix", "small-refactor", according to the type of update.
• If the changes are not small and there is no associated issue, then create the issue first, so we can properly discuss the changes.
• Use dash separated imperative wording related to the issue (e.g., 14-add-tests, 15-fix-model, 16-remove-obsolete-files).

Commit message

• Use imperative or present tense, for instance: Add feature or Fix bug.
• Have informative titles.
• When necessary, add a body with details.
• If there are breaking changes, add the information to the commit message.

Before creating a pull request

• Make sure the tests pass.

• Make sure the pre-commit tests pass.

• Fetch any main updates from upstream and rebase your branch, if necessary:

  git fetch upstream
  git rebase upstream/main BRANCH_NAME

• Then you can open a pull request and work with the reviewer to address any issues.

Building and viewing the documentation locally

The CI workflow builds docs from the docs/ project after developing the current checkout into that environment. To match CI locally:

1. Instantiate the docs environment and develop the package into it:

   julia --project=docs -e '
     using Pkg
     Pkg.develop(Pkg.PackageSpec(path=pwd()))
     Pkg.instantiate()'

2. Build the docs once:

   julia --project=docs docs/make.jl

3. For live preview while editing, start a docs Julia session and serve it:

   julia --project=docs

   using LiveServer
   servedocs()

4. If you want the extra CI parity check, run the doctests too:

   julia --project=docs -e '
     using Documenter: DocMeta, doctest
     using ParallelMCMC
     DocMeta.setdocmeta!(ParallelMCMC, :DocTestSetup, :(using ParallelMCMC); recursive=true)
     doctest(ParallelMCMC)'

If you update the landing-page animation, regenerate it with:

julia docs/src/assets/make_julia_deer_gif.jl

Making a new release

To create a new release:

1. Create a release branch such as release-x.y.z.
2. Update version in Project.toml.
3. Update any release-facing docs you want to ship with the tag.
4. Open and merge the release PR after CI passes.
5. Comment @JuliaRegistrator register on the merge commit or release PR, then wait for the registry PR and auto-merge.
6. After registration, verify that TagBot creates the GitHub tag and that the docs workflow updates the stable docs.