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.
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/kikuchipy/kikuchipy.git
We recommend installing in a conda environment with the Miniconda distribution:
$ conda create --name kikuchipy python=3.8
$ 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.
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.
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 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 doc directory:
$ cd doc
$ make html
The documentation’s html pages are built in the doc/build/html directory
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
address bar.
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.
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.
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.