Contributing
Download the project
Similar to installation, run
julia> using Pkg
julia> Pkg.update()
Updating registry at `~/.julia/registries/General` Updating git-repo `https://github.com/JuliaRegistries/General.git` No Changes to `~/work/Express.jl/Express.jl/docs/Project.toml` No Changes to `~/work/Express.jl/Express.jl/docs/Manifest.toml` [ Info: We haven't cleaned this depot up for a bit, running Pkg.gc()... Active manifest files: 3 found Active artifact files: 3 found Active scratchspaces: 2 found Deleted no artifacts, repos, packages or scratchspaces
julia> pkg"dev Express"
┌ Warning: The Pkg REPL mode is intended for interactive use only, and should not be used from scripts. It is recommended to use the functional API instead. └ @ Pkg.REPLMode /cache/build/default-amdci5-6/julialang/julia-release-1-dot-8/usr/share/julia/stdlib/v1.8/Pkg/src/REPLMode/REPLMode.jl:379 Cloning git-repo `https://github.com/MineralsCloud/Express.jl.git` Resolving package versions... Installed ExpressBase ────── v0.4.0 Installed UnitfulAtomic ──── v1.0.0 Installed Tricks ─────────── v0.1.6 Installed ValSplit ───────── v0.1.0 Installed CompositionsBase ─ v0.1.1 Installed ExprTools ──────── v0.1.8 Installed EasyJobsBase ───── v0.4.0 Installed SimpleWorkflows ── v0.23.0 Updating `~/work/Express.jl/Express.jl/docs/Project.toml` [b12df14e] ~ Express v0.9.2 `~/work/Express.jl/Express.jl` ⇒ v0.9.1 `~/.julia/dev/Express` Updating `~/work/Express.jl/Express.jl/docs/Manifest.toml` [a33af91c] + CompositionsBase v0.1.1 [a8cc5b0e] - Crayons v4.1.1 [a93c6f00] - DataFrames v1.4.3 [e2d170a0] - DataValueInterfaces v1.0.0 [db8ca866] + EasyJobsBase v0.4.0 [e2ba6199] + ExprTools v0.1.8 [b12df14e] ~ Express v0.9.2 `~/work/Express.jl/Express.jl` ⇒ v0.9.1 `~/.julia/dev/Express` [6bf22d12] + ExpressBase v0.4.0 [41ab1584] - InvertedIndices v1.2.0 [82899510] - IteratorInterfaceExtensions v1.0.0 [b964fa9f] - LaTeXStrings v1.3.0 [2dfb63ee] - PooledArrays v1.4.2 [08abe8d2] - PrettyTables v2.2.1 [6a97d125] ↑ SimpleWorkflows v0.16.2 ⇒ v0.23.0 [892a3eda] - StringManipulation v0.3.0 [3783bdb8] - TableTraits v1.0.1 [bd369af6] - Tables v1.10.0 [410a4b4d] + Tricks v0.1.6 [0ca489f0] - TryCatch v0.1.1 [a7773ee8] + UnitfulAtomic v1.0.0 [0625e100] + ValSplit v0.1.0
in the REPL.
Then the package will be cloned to your local machine at a path. On macOS, by default is located at ~/.julia/dev/Express
unless you modify the JULIA_DEPOT_PATH
environment variable. (See Julia's official documentation on how to do this.) In the following text, we will call it PKGROOT
.
Instantiate the project
Go to PKGROOT
, start a new Julia session and run
julia> using Pkg
julia> Pkg.instantiate()
Precompiling project... ✓ Tricks ✓ EasyJobsBase ✓ ExprTools ✓ CompositionsBase ✓ ValSplit ✓ SimpleWorkflows ✓ ExpressBase ✓ UnitfulAtomic ✓ Express 9 dependencies successfully precompiled in 13 seconds. 89 already precompiled. 2 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions
How to build docs
Usually, the up-to-state doc is available in here, but there are cases where users need to build the doc themselves.
After instantiating the project, go to PKGROOT
, run
julia --color=yes docs/make.jl
in your terminal. In a while a folder PKGROOT/docs/build
will appear. Open PKGROOT/docs/build/index.html
with your favorite browser and have fun!
How to run tests
After instantiating the project, go to PKGROOT
, run
julia --color=yes test/runtests.jl
in your terminal.
Style Guide
Follow the style of the surrounding text when making changes. When adding new features please try to stick to the following points whenever applicable.
Julia
- 4-space indentation;
- modules spanning entire files should not be indented, but modules that have surrounding code should;
- do not manually align syntax such as
=
or::
over adjacent lines; - use
function ... end
when a method definition contains more than one top-level expression; - related short-form method definitions don't need a new line between them;
- unrelated or long-form method definitions must have a blank line separating each one;
- surround all binary operators with whitespace except for
::
,^
, and:
; - files containing a single
module ... end
must be named after the module; - method arguments should be ordered based on the amount of usage within the method body;
- methods extended from other modules must follow their inherited argument order, not the above rule;
- explicit
return
should be preferred except in short-form method definitions; - avoid dense expressions where possible e.g. prefer nested
if
s over complex nested?
s; - include a trailing
,
in vectors, tuples, or method calls that span several lines; - do not use multiline comments (
#=
and=#
); - wrap long lines as near to 92 characters as possible, this includes docstrings;
- follow the standard naming conventions used in
Base
.
Markdown
- Use unbalanced
#
headers, i.e. no#
on the right-hand side of the header text; - include a single blank line between top-level blocks;
- do not hard wrap lines;
- use emphasis (
*
) and bold (**
) sparingly; - always use fenced code blocks instead of indented blocks;
- follow the conventions outlined in the Julia documentation page on documentation.