Welcome to Ferrite.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.
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 snippet:
include("docs/liveserver.jl")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
- General information about documenting Julia code in the Julia manual.
- Documentation for
Documenter.jlwhich is used to render the HTML pages. - Documentation for
Literate.jlwhich is used for tutorials/examples.
If you have found a bug or a problem with Ferrite 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.
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.
Ferrite uses Runic.jl for code formatting. You can install Runic with the following command:
julia --project=@runic -e 'using Pkg; Pkg.add(url = "https://github.com/fredrikekre/Runic.jl")'and you can then run the formatter from the root of the repository with:
julia --project=@runic -e 'using Runic; exit(Runic.main(ARGS))' -- --inplace .Refer to the Runic.jl README for more details (such as editor integration).
Ferrite uses pre-commit to run various checks (including Runic formatting). After installing pre-commit (refer to the pre-commit installation instructions) run the following from the root of the repository to configure pre-commit to run before each commit:
pre-commit installNote that this currently requires Runic.jl to be installed in the shared @runic
environment according to the instructions above.