Contributing¶
kikuchipy is meant to be a community maintained project. We welcome contributions in the form of bug reports, documentation, code, feature requests, and more. These guidelines provide resources on how best to contribute.
For new users, checking out the GitHub guides are recommended.
Questions, comments, and feedback¶
Have any questions, comments, suggestions for improvements, or any other inquiries regarding the project? Feel free to ask a question, open an issue or make a pull request in our GitHub repository.
Code of Conduct¶
kikuchipy has a Code of Conduct that should be honoured by everyone who participates in the kikuchipy community.
Setting up a development installation¶
You need a fork of the repository in order to make changes to kikuchipy.
Make a local copy of your forked repository and change directories:
$ git clone https://github.com/your-username/kikuchipy.git
$ cd kikuchipy
Set the upstream
remote to the main kikuchipy repository:
$ git remote add upstream https://github.com/pyxem/kikuchipy.git
We recommend installing in a conda environment with the Miniconda distribution:
$ conda create --name kikuchipy
$ conda activate kikuchipy
Then, install the required dependencies while making the development version
available globally (in the conda
environment):
$ pip install --editable .[dev]
This installs all necessary development dependencies, including those for running tests and building documentation.
Code style¶
The code making up kikuchipy is formatted closely following the Style Guide for
Python Code with The Black Code
style. We
use pre-commit to run black
automatically prior
to each local commit. Please install it in your environment:
$ pre-commit install
Next time you commit some code, your code will be formatted inplace according to our black configuration.
Note that black
won’t format docstrings. We follow the numpydoc
standard.
Comment lines should preferably be limited to 72 characters.
Package imports should be structured into three blocks with blank lines between
them (descending order): standard library (like os
and typing
), third
party packages (like numpy
and hyperspy
) and finally kikuchipy imports.
Making changes¶
Create a new feature branch:
$ git checkout master -b your-awesome-feature-name
When you’ve made some changes you can view them with:
$ git status
Add and commit your created, modified or deleted files:
$ git add my-file-or-directory
$ git commit -s -m "An explanatory commit message"
The -s
makes sure that you sign your commit with your GitHub-registered
email as the author. You can set this up
following this GitHub guide.
Keeping your branch up-to-date¶
Switch to the master
branch:
$ git checkout master
Fetch changes and update master
:
$ git pull upstream master --tags
Update your feature branch:
$ git checkout your-awesome-feature-name
$ git merge master
Sharing your changes¶
Update your remote branch:
$ git push -u origin your-awesome-feature-name
You can then make a pull request to
kikuchipy’s master
branch. Good job!
Building and writing documentation¶
We use Sphinx for documenting functionality. Install necessary dependencies to build the documentation:
$ pip install --editable .[doc]
Then, build the documentation from the doc
directory:
$ cd doc
$ make html
The documentation’s HTML pages are built in the doc/build/html
directory
from files in the reStructuredText (reST)
plaintext markup language. They should be accessible in the browser by typing
file:///your-absolute/path/to/kikuchipy/doc/build/html/index.html
in the
address bar.
Tips for writing Jupyter Notebooks that are meant to be converted to reST text files by nbsphinx:
All notebooks should have a Markdown (MD) cell with this message at the top, “This notebook is part of the kikuchipy documentation https://kikuchipy.org. Links to the documentation won’t work from the notebook.”, and have
"nbsphinx": "hidden"
in the cell metadata so that the message is not visible when displayed in the documentation.Use
_ = ax[0].imshow(...)
to disable Matplotlib output if a Matplotlib command is the last line in a cell.Refer to our API reference with this general MD
[fft_filter()](reference.rst#kikuchipy.signals.EBSD.fft_filter)
. Remember to add the parentheses()
.Reference external APIs via standard MD like
[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)
.The Sphinx gallery thumbnail used for a notebook is set by adding the
nbsphinx-thumbnail
tag to a code cell with an image output. The notebook must be added to the gallery in the README.rst to be included in the documentation pages.
Running and writing tests¶
All functionality in kikuchipy is tested via the pytest framework. The tests reside in a test
directory
within each module. Tests are short methods that call functions in kikuchipy
and compare resulting output values with known answers. Install necessary
dependencies to run the tests:
$ pip install --editable .[tests]
Some useful fixtures, like a
dummy scan and corresponding background pattern, are available in the
conftest.py
file.
Note
Some kikuchipy.data
module tests check that data not part of the
package distribution can be downloaded from the kikuchipy-data GitHub
repository, thus downloading some
datasets of ~15 MB to your local cache.
To run the tests:
$ pytest --cov --pyargs kikuchipy
The --cov
flag makes coverage.py print a nice report in the
terminal. For an even nicer presentation, you can use coverage.py
directly:
$ coverage html
Then, you can open the created htmlcov/index.html
in the browser and inspect
the coverage in more detail.
Adding data to the data module¶
Test data for user guides and tests are included in the kikuchipy.data
module via the pooch Python library.
These are listed in a file registry (kikuchipy.data._registry.py) with their
file verification string (hash, SHA256, obtain with e.g. sha256sum <file>) and
location, the latter potentially not within the package but from the
kikuchipy-data repository, since
some files are considered too large to include in the package.
If a required dataset isn’t in the package, but is in the registry, it can be
downloaded from the repository when the user passes allow_download=True to
e.g. nickel_ebsd_large()
. The dataset is then downloaded
to a local cache, e.g. /home/user/.cache/kikuchipy/. Pooch handles
downloading, caching, version control, file verification (against hash) etc. If
we have updated the file hash, pooch will redownload it. If the file is
available in the cache, it can be loaded as the other files in the data module.
The desired data cache directory used by pooch can be set with a global KIKUCHIPY_DATA_DIR variable locally, e.g. by setting export KIKUCHIPY_DATA_DIR=~/kikuchipy_data in ~/.bashrc.
Continuous integration (CI)¶
We use GitHub Actions to ensure that kikuchipy can be installed on Windows, macOS and Linux (Ubuntu). After a successful installation, the CI server runs the tests. After the tests return no errors, code coverage is reported to Coveralls.