GitHub

Developer documentation

Contributing guidelines

If you haven't, please read the Contributing guidelines first.

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

First time clone

If you have writing rights

If you have writing rights, you don't have to fork. Instead, simply clone and skip ahead. Whenever upstream is mentioned, use origin instead.

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/your_username/IntrinsicTimescales.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.

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

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

Atomic git commits

Try to create "atomic git commits" (recommended reading: The Utopic Git History).

  • Make sure the 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

Following the latest suggestions, we recommend using LiveServer to build the documentation. Here is how you do it:

  1. Run julia --project=docs to open Julia in the environment of the docs.
  2. If this is the first time building the docs
    1. Press ] to enter pkg mode
    2. Run pkg> dev . to use the development version of your package
    3. Press backspace to leave pkg mode
  3. Run julia> using LiveServer
  4. Run julia> servedocs()