Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (101 loc) · 5.46 KB

CONTRIBUTING.md

File metadata and controls

138 lines (101 loc) · 5.46 KB

CriticalTransitions.jl contributor guide

Welcome to CriticalTransitions.jl contributor documentation! In this document you find information about:

If you are new to open source development in general there are many guides online to help you get started, for example first-contributions. Another great resource, which specifically discusses Julia contributions, is the video Open source, Julia packages, git, and GitHub.

Documentation

Contributing to documentation is a great way to get started with any new project. As a new user you have a unique perspective of what things need to be documented and explained better -- if something confuses you, chances are you're not alone. Remember that also simple changes like fixing typos are welcome contributions. If you are looking for specific things to work on you can look at open issues.

Small changes can be done easily in GitHub's web interface (see Editing files). Every page in the documentation have an Edit on GitHub button at the top, which takes you to the correct source file. The video Making Julia documentation better guides you through these steps.

Making larger changes is easier locally after cloning the repository. With a local repository you can also preview the changes in your own browser. After starting a Julia REPL in the root of the repository you can execute the following command:

make servedocs

Alternatively, you can manually run:

julia --project=docs -e 'using LiveServer; LiveServer.servedocs()'

This uses LiveServer.jl to launch a local webserver which you can visit at http://localhost:8000. LiveServer.jl will monitor changes to the source files. When you make a change, and save the file, LiveServer.jl will automatically rebuild the documentation, and automatically refresh your browser window. Note that the first build may take longer, but subsequent runs should be substantially faster and give you almost instant feedback in the browser.

Useful resources

Referencing literature

To reference scientific literature in the package documentation (where appropriate), we use DocumenterCitations.jl. To add a reference, add its bibtex entry to docs/src/refs.bib and cite it in the documentation using the @cite or @citet commands.

Reporting issues

If you have found a bug or a problem with CriticalTransitions you can open an issue. Try to include as much information about the problem as possible and preferably some code that can be copy-pasted to reproduce it (see How to create a Minimal, Reproducible Example).

If you can identify a fix for the bug you can submit a pull request without first opening an issue, see Code changes.

Code changes

Bug fixes and improvements to the code, or to the unit tests are always welcome. If you have ideas about new features or functionality it might be good to first open an issue or discussion to get feedback before spending too much time implementing something.

If you are looking for specific things to work on you can look at open issues.

Remember to always include (when applicable): i) unit tests which exercises the new code, ii) documentation, iii) a note in the CHANGELOG.md file.

Code formatting

CriticalTransitions uses Runic.jl for code formatting. Install Runic once as a Pkg app (Julia 1.12+) so the runic binary is available in any environment:

using Pkg; Pkg.Apps.add("Runic")

Make sure ~/.julia/bin is on your PATH. Then format the code with:

make format

or manually with:

runic --inplace .

Runic enforces a single fixed style with no configuration options. All pull requests are automatically checked for proper formatting via GitHub Actions.

Testing

You can run the test suite by running:

make test

or manually with:

using Pkg; Pkg.test()

Make sure all tests pass before submitting a pull request. If you add new functionality, please include appropriate tests to verify the new code works as expected.