Edit on GitHub

Contributing

Welcome! This document explains some ways you can contribute to MillerIndices.

Code of conduct

This project and everyone participating in it is governed by the "Contributor Covenant Code of Conduct". By participating, you are expected to uphold this code.

Join the community forum

First up, join the community forum.

The forum is a good place to ask questions about how to use MillerIndices. You can also use the forum to discuss possible feature requests and bugs before raising a GitHub issue (more on this below).

Aside from asking questions, the easiest way you can contribute to MillerIndices is to help answer questions on the forum!

Improve the documentation

Chances are, if you asked (or answered) a question on the community forum, then it is a sign that the documentation could be improved. Moreover, since it is your question, you are probably the best-placed person to improve it!

The docs are written in Markdown and are built using Documenter.jl. You can find the source of all the docs here.

If your change is small (like fixing typos, or one or two sentence corrections), the easiest way to do this is via GitHub's online editor. (GitHub has help on how to do this.)

If your change is larger, or touches multiple files, you will need to make the change locally and then use Git to submit a pull request. (See Contribute code to MillerIndices below for more on this.)

File a bug report

Another way to contribute to MillerIndices is to file bug reports.

Make sure you read the info in the box where you write the body of the issue before posting. You can also find a copy of that info here.

Tip

If you're unsure whether you have a real bug, post on the community forum first. Someone will either help you fix the problem, or let you know the most appropriate place to open a bug report.

Contribute code to MillerIndices

Finally, you can also contribute code to MillerIndices!

Warning

If you do not have experience with Git, GitHub, and Julia development, the first steps can be a little daunting. However, there are lots of tutorials available online, including:

Once you are familiar with Git and GitHub, the workflow for contributing code to MillerIndices is similar to the following:

Step 1: decide what to work on

The first step is to find an open issue (or open a new one) for the problem you want to solve. Then, before spending too much time on it, discuss what you are planning to do in the issue to see if other contributors are fine with your proposed changes. Getting feedback early can improve code quality, and avoid time spent writing code that does not get merged into MillerIndices.

Tip

At this point, remember to be patient and polite; you may get a lot of comments on your issue! However, do not be afraid! Comments mean that people are willing to help you improve the code that you are contributing to MillerIndices.

Step 2: fork MillerIndices

Go to https://github.com/MineralsCloud/MillerIndices.jl and click the "Fork" button in the top-right corner. This will create a copy of MillerIndices under your GitHub account.

Step 3: install MillerIndices locally

Similar to installation, open the Julia REPL and run:

julia> using Pkg
julia> Pkg.update()    Updating registry at `~/.julia/registries/General.toml`
   Installed RegistryInstances ─────── v0.1.0
   Installed IOCapture ─────────────── v0.2.3
   Installed AbstractTrees ─────────── v0.4.4
   Installed MarkdownAST ───────────── v0.1.2
   Installed LazilyInitializedFields ─ v1.2.1
   Installed Documenter ────────────── v1.1.0
    Updating `~/work/MillerIndices.jl/MillerIndices.jl/docs/Project.toml`
  [e30172f5] ↑ Documenter v0.27.23 ⇒ v1.1.0
    Updating `~/work/MillerIndices.jl/MillerIndices.jl/docs/Manifest.toml`
  [1520ce14] + AbstractTrees v0.4.4
  [e30172f5] ↑ Documenter v0.27.23 ⇒ v1.1.0
  [b5f81e59] ↑ IOCapture v0.2.2 ⇒ v0.2.3
  [682c06a0] ↑ JSON v0.21.3 ⇒ v0.21.4
  [0e77f7df] + LazilyInitializedFields v1.2.1
  [d0879d2d] + MarkdownAST v0.1.2
  [69de0a69] ↑ Parsers v2.5.3 ⇒ v2.7.2
  [aea7be01] + PrecompileTools v1.2.0
  [21216c6a] ↑ Preferences v1.3.0 ⇒ v1.4.1
  [2792f1a3] + RegistryInstances v0.1.0
  [66db9d55] - SnoopPrecompile v1.0.3
  [0dad84c5] + ArgTools v1.1.1
  [f43a241f] + Downloads v1.6.0
  [7b1f6079] + FileWatching
  [b27032c2] + LibCURL v0.6.3
  [44cfe95a] + Pkg v1.9.2
  [a4e569a6] + Tar v1.10.0
  [cf7118a7] + UUIDs
  [deac9b47] + LibCURL_jll v7.84.0+0
  [29816b5a] + LibSSH2_jll v1.10.2+0
  [c8ffd9c3] + MbedTLS_jll v2.28.2+0
  [14a3606d] + MozillaCACerts_jll v2022.10.11
  [83775a58] + Zlib_jll v1.2.13+0
  [8e850ede] + nghttp2_jll v1.48.0+0
  [3f19e933] + p7zip_jll v17.4.0+0
Precompiling project...
  ✓ LazilyInitializedFields
  ✓ CompilerSupportLibraries_jll
  ✓ AbstractTrees
  ✓ IOCapture
  ✓ RegistryInstances
  ✓ MarkdownAST
  ✓ Documenter
  7 dependencies successfully precompiled in 36 seconds. 13 already precompiled.
  2 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions
[ Info: We haven't cleaned this depot up for a bit, running Pkg.gc()...
      Active manifest files: 3 found
      Active artifact files: 0 found
      Active scratchspaces: 0 found
     Deleted no artifacts, repos, packages or scratchspaces
julia> Pkg.develop("MillerIndices")     Cloning git-repo `https://github.com/MineralsCloud/MillerIndices.jl.git`
   Resolving package versions...
   Installed Compat ────────────── v4.10.0
   Installed Reexport ──────────── v1.2.2
   Installed StructEquality ────── v2.1.0
   Installed AnonymousEnums ────── v0.1.1
   Installed CrystallographyBase ─ v0.13.0
   Installed CrystallographyCore ─ v0.3.2
    Updating `~/work/MillerIndices.jl/MillerIndices.jl/docs/Project.toml`
  [f41335bc] ~ MillerIndices v0.1.0 `~/work/MillerIndices.jl/MillerIndices.jl` ⇒ v0.1.0 `~/.julia/dev/MillerIndices`
    Updating `~/work/MillerIndices.jl/MillerIndices.jl/docs/Manifest.toml`
  [1b8a1bdb] + AnonymousEnums v0.1.1
  [34da2185] + Compat v4.10.0
  [93b1d1cd] + CrystallographyBase v0.13.0
⌅ [80545937] + CrystallographyCore v0.3.2
  [f41335bc] ~ MillerIndices v0.1.0 `~/work/MillerIndices.jl/MillerIndices.jl` ⇒ v0.1.0 `~/.julia/dev/MillerIndices`
  [189a3867] + Reexport v1.2.2
  [6ec83bb0] + StructEquality v2.1.0
        Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated -m`

Then the package will be cloned to your local machine. On *nix systems, the default path is ~/.julia/dev/MillerIndices unless you modify the JULIA_DEPOT_PATH environment variable. If you're on Windows, this will be C:\\Users\\<my_name>\\.julia\\dev\\MillerIndices. In the following text, we will call it PKGROOT.

Go to PKGROOT, start a new Julia session and run

julia> using Pkg
julia> Pkg.instantiate()Precompiling project...
  ✓ Reexport
  ✓ AnonymousEnums
  ✓ Compat
  ✓ Compat → CompatLinearAlgebraExt
  ✓ StructEquality
  ✓ CrystallographyCore
  ✓ CrystallographyBase
  ✓ MillerIndices
  8 dependencies successfully precompiled in 5 seconds. 19 already precompiled.
  1 dependency precompiled but a different version is currently loaded. Restart julia to access the new version

to instantiate the project.

Step 4: checkout a new branch

Note

In the following, replace any instance of GITHUB_ACCOUNT with your GitHub username.

The next step is to checkout a development branch. In a terminal (or command prompt on Windows), run:

cd ~/.julia/dev/MillerIndices

git remote add GITHUB_ACCOUNT https://github.com/GITHUB_ACCOUNT/MillerIndices.jl.git

git checkout main

git pull

git checkout -b my_new_branch

Step 5: make changes

Now make any changes to the source code inside the ~/.julia/dev/MillerIndices directory.

Make sure you:

Tip

When you change the source code, you'll need to restart Julia for the changes to take effect. This is a pain, so install Revise.jl.

Step 6a: test your code changes

To test that your changes work, run the MillerIndices test-suite by opening Julia and running:

julia> cd("~/.julia/dev/MillerIndices")ERROR: IOError: cd("~/.julia/dev/MillerIndices"): no such file or directory (ENOENT)
julia> using Pkg
julia> Pkg.activate(".")  Activating new project at `~/work/MillerIndices.jl/MillerIndices.jl/docs/build/developers`
julia> Pkg.test()ERROR: trying to test unnamed project
Warning

Running the tests might take a long time.

Tip

If you're using Revise.jl, you can also run the tests by calling include:

include("test/runtests.jl")

This can be faster if you want to re-run the tests multiple times.

Step 6b: test your documentation changes

Open Julia, then run:

julia> cd("~/.julia/dev/MillerIndices/docs")ERROR: IOError: cd("~/.julia/dev/MillerIndices/docs"): no such file or directory (ENOENT)
julia> using Pkg
julia> Pkg.activate(".")  Activating new project at `~/work/MillerIndices.jl/MillerIndices.jl/docs/build/developers`
julia> include("src/make.jl")ERROR: SystemError: opening file "/home/runner/work/MillerIndices.jl/MillerIndices.jl/docs/build/developers/src/make.jl": No such file or directory

After a while, a folder PKGROOT/docs/build will appear. Open PKGROOT/docs/build/index.html with your favorite browser, and have fun!

Warning

Building the documentation might take a long time.

Tip

If there's a problem with the tests that you don't know how to fix, don't worry. Continue to step 5, and one of the MillerIndices contributors will comment on your pull request telling you how to fix things.

Step 7: make a pull request

Once you've made changes, you're ready to push the changes to GitHub. Run:

cd ~/.julia/dev/MillerIndices

git add .

git commit -m "A descriptive message of the changes"

git push -u GITHUB_ACCOUNT my_new_branch

Then go to https://github.com/MineralsCloud/MillerIndices.jl/pulls and follow the instructions that pop up to open a pull request.

Step 8: respond to comments

At this point, remember to be patient and polite; you may get a lot of comments on your pull request! However, do not be afraid! A lot of comments means that people are willing to help you improve the code that you are contributing to MillerIndices.

To respond to the comments, go back to step 5, make any changes, test the changes in step 6, and then make a new commit in step 7. Your PR will automatically update.

Step 9: cleaning up

Once the PR is merged, clean-up your Git repository ready for the next contribution!

cd ~/.julia/dev/MillerIndices

git checkout main

git pull
Note

If you have suggestions to improve this guide, please make a pull request! It's particularly helpful if you do this after your first pull request because you'll know all the parts that could be explained better.

Thanks for contributing to MillerIndices!