Contributing

Contributing

Download the project

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 ifs 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.