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.
Setting up a development installation¶
Make a local copy of your forked repository and change directories:
$ git clone https://github.com/your-username/kikuchipy.git $ cd kikuchipy
upstream remote to the main kikuchipy repository:
$ git remote add upstream https://github.com/kikuchipy/kikuchipy.git
$ conda create --name kikuchipy python=3.8 $ conda activate kikuchipy
Then, install the required dependencies while making the development version
available globally (in the
$ pip install --editable .[dev]
This installs all necessary development dependencies, including those for running tests and building documentation.
The code making up kikuchipy is formatted closely following the Style Guide for
Python Code with The Black Code
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.
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"
Keeping your branch up-to-date¶
Switch to the
$ git checkout master
Fetch changes and update
$ git pull upstream master --tags
Update your feature branch:
$ git checkout your-awesome-feature-name $ git merge master
Building the documentation¶
We use Sphinx for documenting functionality. Install necessary dependencies to build the documentation:
$ pip install --editable .[doc]
Then, build the documentation from the
$ cd doc $ make html
html pages are built in the
from files in the reStructuredText
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
Running and writing tests¶
All functionality in kikuchipy is tested via the pytest framework. The tests reside in a
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
To run the tests:
$ pytest --cov --pyargs kikuchipy
--cov flag makes coverage.py print a nice report in the
terminal. For an even nicer presentation, you can use
$ coverage html
Then, you can open the created
htmlcov/index.html in the browser and inspect
the coverage in more detail.
Code of Conduct¶
kikuchipy has a Code of Conduct that should be honoured by everyone who participates in the kikuchipy community.
Questions, comments, and feedback¶
Have any questions, comments, suggestions for improvements, or any other inquiries regarding the project? Feel free to open an issue in our GitHub Issue Tracker.