From 7f265af0c84a6ef1424270bff31c337e0e6d9245 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5kon=20Wiik=20=C3=85nes?= Date: Tue, 11 Jan 2022 11:58:50 +0100 Subject: [PATCH 1/3] Improve testing of private Numba functions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- kikuchipy/_rotation/__init__.py | 9 ++++++++- kikuchipy/_rotation/tests/test_rotation.py | 22 +++++++++++++++------- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/kikuchipy/_rotation/__init__.py b/kikuchipy/_rotation/__init__.py index a5917d19..3e9b0533 100644 --- a/kikuchipy/_rotation/__init__.py +++ b/kikuchipy/_rotation/__init__.py @@ -62,10 +62,17 @@ def _rotation_from_euler(alpha: float, beta: float, gamma: float) -> np.ndarray: c = np.cos(0.5 * beta) s = np.sin(0.5 * beta) + # fmt: off rotation = np.array( - (c * np.cos(sigma), -s * np.cos(delta), -s * np.sin(delta), -c * np.sin(sigma)), + ( + c * np.cos(sigma), + -s * np.cos(delta), + -s * np.sin(delta), + -c * np.sin(sigma) + ), dtype=np.float64, ) + # fmt: on if rotation[0] < 0: rotation = -rotation diff --git a/kikuchipy/_rotation/tests/test_rotation.py b/kikuchipy/_rotation/tests/test_rotation.py index b13adcc8..500fb38d 100644 --- a/kikuchipy/_rotation/tests/test_rotation.py +++ b/kikuchipy/_rotation/tests/test_rotation.py @@ -16,7 +16,8 @@ # along with kikuchipy. If not, see . import numpy as np -from orix import quaternion, vector +from orix.quaternion import Rotation +from orix.vector import Vector3d import kikuchipy as kp @@ -38,15 +39,22 @@ def test_rotate_vector(self): sample_tilt=70, ) dc = dc.reshape((-1, 3)) - rotated_dc = kp._rotation._rotate_vector.py_func(rot, dc) - rot_orix = quaternion.Rotation(rot) - dc_orix = vector.Vector3d(dc) + rot_orix = Rotation(rot) + dc_orix = Vector3d(dc) rotated_dc_orix = rot_orix * dc_orix - assert np.allclose(rotated_dc, rotated_dc_orix.data, atol=1e-3) + rotated_dc = kp._rotation._rotate_vector(rot, dc) + rotated_dc_py = kp._rotation._rotate_vector.py_func(rot, dc) + + assert np.allclose(rotated_dc, rotated_dc_py, atol=1e-3) + assert np.allclose(rotated_dc_py, rotated_dc_orix.data, atol=1e-3) def test_rotation_from_euler(self): euler = np.array([1, 2, 3]) - rot_orix = quaternion.Rotation.from_euler(euler).data - assert np.allclose(rot_orix, kp._rotation._rotation_from_euler.py_func(*euler)) + rot_orix = Rotation.from_euler(euler).data + rot_numba = kp._rotation._rotation_from_euler(*euler) + rot_numba_py = kp._rotation._rotation_from_euler.py_func(*euler) + + assert np.allclose(rot_numba, rot_numba_py) + assert np.allclose(rot_numba_py, rot_orix) From 80cc10cc739bb27c3b7421337312f569a4e90f28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5kon=20Wiik=20=C3=85nes?= Date: Tue, 11 Jan 2022 11:59:41 +0100 Subject: [PATCH 2/3] Add hints for testing Numba functions to contributing guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/contributing.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/contributing.rst b/doc/contributing.rst index 1e836a1e..32f7e52d 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -243,6 +243,15 @@ Docstring examples are tested `with pytest pytest --doctest-modules --ignore-glob=kikuchipy/*/tests +Tips for writing tests of Numba decorated functions: + +- A Numba decorated function `numba_func()` is only covered if it is called in the test + as `numba_func.py_func()`. +- Always test a Numba decorated function calling `numba_func()` directly, in addition to + `numba_func.py_func()`, because the machine code function might give different results + on different OS with the same Python code. See `this issue for a case where this + happened `_. + Adding data to the data module ============================== From a0fa9e1729f9b763ac81b651f4edb3fc7a93b28c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5kon=20Wiik=20=C3=85nes?= Date: Tue, 11 Jan 2022 12:28:11 +0100 Subject: [PATCH 3/3] Increase visibility of contributing guide and code of conduct MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- CODE_OF_CONDUCT.rst | 157 +++++++++++++++++++++ CONTRIBUTING.rst | 294 +++++++++++++++++++++++++++++++++++++++ MANIFEST.in | 2 + doc/code_of_conduct.rst | 158 +-------------------- doc/contributing.rst | 295 +--------------------------------------- 5 files changed, 457 insertions(+), 449 deletions(-) create mode 100644 CODE_OF_CONDUCT.rst create mode 100644 CONTRIBUTING.rst diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst new file mode 100644 index 00000000..c8523196 --- /dev/null +++ b/CODE_OF_CONDUCT.rst @@ -0,0 +1,157 @@ +========================= +kikuchipy Code of Conduct +========================= + +Introduction +============ + +This code of conduct applies to all spaces managed by the kikuchipy project, +including all public and private mailing lists, issue trackers, wikis, blogs, +Twitter, and any other communication channel used by our community. The +kikuchipy project does not organise in-person events, however events related to +our community should have a code of conduct similar in spirit to this one. + +This code of conduct should be honoured by everyone who participates in the +kikuchipy community formally or informally, or claims any affiliation with the +project, in any project-related activities and especially when representing the +project, in any role. + +This code is not exhaustive or complete. It serves to distill our common +understanding of a collaborative, shared environment and goals. Please try to +follow this code in spirit as much as in letter, to create a friendly and +productive environment that enriches the surrounding community. + +Specific guidelines +=================== + +We strive to: + +1. Be open. We invite anyone to participate in our community. We prefer to use + public methods of communication for project-related messages, unless + discussing something sensitive. This applies to messages for help or + project-related support, too; not only is a public-support request much more + likely to result in an answer to a question, it also ensures that any + inadvertent mistakes in answering are more easily detected and corrected. + +2. Be empathetic, welcoming, friendly, and patient. We work together to resolve + conflict, and assume good intentions. We may all experience some frustration + from time to time, but we do not allow frustration to turn into a personal + attack. A community where people feel uncomfortable or threatened is not a + productive one. + +3. Be collaborative. Our work will be used by other people, and in turn we will + depend on the work of others. When we make something for the benefit of the + project, we are willing to explain to others how it works, so that they can + build on the work to make it even better. Any decision we make will affect + users and colleagues, and we take those consequences seriously when making + decisions. + +4. Be inquisitive. Nobody knows everything! Asking questions early avoids many + problems later, so we encourage questions, although we may direct them to the + appropriate forum. We will try hard to be responsive and helpful. + +5. Be careful in the words that we choose. We are careful and respectful in our + communication and we take responsibility for our own speech. Be kind + others. Do not insult or put down other participants. We will not accept + harassment or other exclusionary behaviour, such as: + + - Violent threats or language directed against another person. + - Sexist, racist, ableist, or otherwise discriminatory jokes and language. + - Posting sexually explicit or violent material. + - Posting (or threatening to post) other people's personally identifying + information ("doxing"). + - Sharing private content, such as emails sent privately or non-publicly, or + unlogged forums such as IRC channel history, without the sender's consent. + - Personal insults, especially those using racist, sexist, or ableist terms. + - Intentional or repeated misgendering of participants who have explicitly + requested to be addressed by specific pronouns. + - Unwelcome sexual attention. + - Excessive profanity. Please avoid swearwords; people differ greatly in + their sensitivity to swearing. + - Repeated harassment of others. In general, if someone asks you to stop, + then stop. + - Advocating for, or encouraging, any of the above behaviour. + +Diversity statement +=================== + +The kikuchipy project welcomes and encourages participation by everyone. We are +committed to being a community that everyone enjoys being part of. Although we +may not always be able to accommodate each individual's preferences, we try our +best to treat everyone kindly. + +No matter how you identify yourself or how others perceive you: we welcome you. +Though no list can hope to be comprehensive, we explicitly honour diversity in: +age, culture, ethnicity, genotype, gender identity or expression, language, +national origin, neurotype, phenotype, political beliefs, profession, race, +religion, sexual orientation, socioeconomic status, subculture and technical +ability, to the extent that these do not conflict with this code of conduct. + +Though we welcome people fluent in all languages, kikuchipy development is +conducted in English. + +Standards for behaviour in the kikuchipy community are detailed in the Code of +Conduct above. Participants in our community should uphold these standards in +all their interactions and help others to do so as well (see next section). + +Reporting guidelines +==================== + +We know that it is painfully common for internet communication to start at or +devolve into obvious and flagrant abuse. We also recognize that sometimes people +may have had a bad day, or be unaware of some of the guidelines in this Code of +Conduct. Please keep this in mind when deciding how to respond to a breach of +this Code. + +For clearly intentional breaches, report those to the Code of Conduct Committee +(see below). For possibly unintentional breaches, you may reply to the person +and point out this Code of Conduct (either in public or in private, whatever is +most appropriate). If you would prefer not to do that, please feel free to +report to the code of conduct committee directly, or ask the committee for +advice, in confidence. + +You can report issues to the kikuchipy Code of Conduct Committee, at +kikuchipy-conduct@googlegroups.com. Currently, the committee consists of: + +* `Håkon Wiik Ånes `_ (chair) +* `Tina Bergh `_ + +Incident reporting resolution & Code of Conduct enforcement +=========================================================== + +*This section summarizes the most important points, more details can be found +in* :doc:`report_handling_manual`. + +We will investigate and respond to all complaints. The kikuchipy Code of Conduct +Committee will protect the identity of the reporter, and treat the content of +complaints as confidential (unless the reporter agrees otherwise). + +In case of severe and obvious breaches, e.g. personal threat or violent, +sexist or racist language, we will immediately disconnect the originator from +kikuchipy communication channels; please see the manual for details. + +In cases not involving clear severe and obvious breaches of this code of +conduct, the process for acting on any received code of conduct violation report +will be: + +1. acknowledge report is received + +2. reasonable discussion/feedback + +3. mediation (if feedback didn't help, and only if both reporter and reportee + agree to this) + +4. enforcement via transparent decision (see :ref:`resolutions`) by the Code of + Conduct Committee + +The committee will respond to any report as soon as possible, and at most within +72 hours. + +Endnotes +======== + +We are thankful to the groups behind the following documents, from which we drew +content and inspiration: + +* `napari Code of Conduct `_ +* `NumPy Code of Conduct `_ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..377a200d --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,294 @@ +============ +Contributing +============ + +kikuchipy is a community maintained project. We welcome contributions in the form of bug +reports, documentation, code, feature requests, and more. The source code is hosted on +`GitHub `_. These guidelines provide resources on +how best to contribute. + +.. tip:: + + This guide can look intimidating to people who want to contribute, but have limited + experience with tools like ``git``, ``pytest``, and ``sphinx``. The shortest route + to start contributing is to create a GitHub account and explain what you want to do + `in an issue `_. + +This project follows the `all-contributors +`_ specification. + +Questions, comments, and feedback +================================= + +Have a question, comment, suggestion 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. We also have a +`Gitter chat `_. + +Code of Conduct +=============== + +kikuchipy has a :doc:`Code of Conduct ` that should be honoured by +everyone who participates in the kikuchipy community. + +.. _setting-up-a-development-installation: + +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 kp-dev + conda activate kp-dev + +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 +``black``. + +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 +============== + +If you want to add a new feature, branch off of the ``develop`` branch, and when you +want to fix a bug, branch off of ``main`` instead. + +To create a new feature branch that tracks the upstream development branch:: + + git checkout develop -b your-awesome-feature-name upstream/develop + +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 +============================== + +If you are adding a new feature, make sure to merge ``develop`` into your feature +branch. If you are fixing a bug, merge ``main`` into your bug fix branch instead. + +To update a feature branch, switch to the ``develop`` branch:: + + git checkout develop + +Fetch changes from the upstream branch and update ``develop``:: + + git pull upstream develop --tags + +Update your feature branch:: + + git checkout your-awesome-feature-name + git merge develop + +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 +``develop`` branch for new features and ``main`` branch for bug fixes. 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 ``()`` for functions and methods. +- 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. +- The Furo Sphinx theme displays the documentation in a light or dark theme, depending + on the browser/OS setting. It is important to make sure the documentation is readable + with both themes. This means explicitly printing the signal axes manager, like + ``print(s.axes_manager)``, and displaying all figures with a white background for axes + labels and ticks and figure titles etc. to be readable. + +In general, we run all notebooks every time the documentation is built with Sphinx, to +ensure that all notebooks are compatible with the current API at all times. This is +important! For computationally expensive notebooks however, we store the cell outputs so +the documentation doesn't take too long to build, either by us locally or the Read The +Docs GitHub action. To check that the notebooks with cell outputs stored are compatible +with the current API as well, we run a scheduled GitHub Action every Monday morning +which checks that the notebooks run OK and that they produced the same output now as +when they were last executed. We use `nbval `_ +for this. + +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 :mod:`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. + +To run only a specific test function or class, .e.g the ``TestEBSD`` class:: + + pytest -k TestEBSD + +This is useful when you only want to run a specific test and not the full test suite, +e.g. when you're creating or updating a test. But remember to run the full test suite +before pushing! + +Docstring examples are tested `with pytest +`_ as well:: + + pytest --doctest-modules --ignore-glob=kikuchipy/*/tests + +Tips for writing tests of Numba decorated functions: + +- A Numba decorated function ``numba_func()`` is only covered if it is called in the + test as ``numba_func.py_func()``. +- Always test a Numba decorated function calling ``numba_func()`` directly, in addition + to ``numba_func.py_func()``, because the machine code function might give different + results on different OS with the same Python code. See `this issue + `_ for a case where this happened. + +Adding data to the data module +============================== + +Test data for user guides and tests are included in the :mod:`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 `) 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. +:func:`~kikuchipy.data.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 re-download 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`. + +Improving performance +===================== +When we write code, it's important that we (1) get the correct result, (2) don't fill up +memory, and (3) that the computation doesn't take too long. To keep memory in check, we +should use `Dask `_ wherever possible. To speed up +computations, we should use `Numba `_ wherever +possible. + +Continuous integration (CI) +=========================== + +We use `GitHub Actions `_ to ensure that +kikuchipy can be installed on Windows, macOS and Linux (Ubuntu). After a successful +installation of the package, the CI server runs the tests. After the tests return no +errors, code coverage is reported to `Coveralls +`_. Add "[skip ci]" or to a +commit message to skip this workflow on any commit to a pull request, as explained diff --git a/MANIFEST.in b/MANIFEST.in index 932c41f8..cf1c1092 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,6 @@ include CHANGELOG.rst +include CODE_OF_CONDUCT.rst +include CONTRIBUTING.rst include kikuchipy/hyperspy_extension.yaml include LICENSE include MANIFEST.in diff --git a/doc/code_of_conduct.rst b/doc/code_of_conduct.rst index c8523196..ec57779f 100644 --- a/doc/code_of_conduct.rst +++ b/doc/code_of_conduct.rst @@ -1,157 +1,3 @@ -========================= -kikuchipy Code of Conduct -========================= +.. This is a stub, see the top level CODE_OF_CONDUCT.rst file for the code of conduct. -Introduction -============ - -This code of conduct applies to all spaces managed by the kikuchipy project, -including all public and private mailing lists, issue trackers, wikis, blogs, -Twitter, and any other communication channel used by our community. The -kikuchipy project does not organise in-person events, however events related to -our community should have a code of conduct similar in spirit to this one. - -This code of conduct should be honoured by everyone who participates in the -kikuchipy community formally or informally, or claims any affiliation with the -project, in any project-related activities and especially when representing the -project, in any role. - -This code is not exhaustive or complete. It serves to distill our common -understanding of a collaborative, shared environment and goals. Please try to -follow this code in spirit as much as in letter, to create a friendly and -productive environment that enriches the surrounding community. - -Specific guidelines -=================== - -We strive to: - -1. Be open. We invite anyone to participate in our community. We prefer to use - public methods of communication for project-related messages, unless - discussing something sensitive. This applies to messages for help or - project-related support, too; not only is a public-support request much more - likely to result in an answer to a question, it also ensures that any - inadvertent mistakes in answering are more easily detected and corrected. - -2. Be empathetic, welcoming, friendly, and patient. We work together to resolve - conflict, and assume good intentions. We may all experience some frustration - from time to time, but we do not allow frustration to turn into a personal - attack. A community where people feel uncomfortable or threatened is not a - productive one. - -3. Be collaborative. Our work will be used by other people, and in turn we will - depend on the work of others. When we make something for the benefit of the - project, we are willing to explain to others how it works, so that they can - build on the work to make it even better. Any decision we make will affect - users and colleagues, and we take those consequences seriously when making - decisions. - -4. Be inquisitive. Nobody knows everything! Asking questions early avoids many - problems later, so we encourage questions, although we may direct them to the - appropriate forum. We will try hard to be responsive and helpful. - -5. Be careful in the words that we choose. We are careful and respectful in our - communication and we take responsibility for our own speech. Be kind - others. Do not insult or put down other participants. We will not accept - harassment or other exclusionary behaviour, such as: - - - Violent threats or language directed against another person. - - Sexist, racist, ableist, or otherwise discriminatory jokes and language. - - Posting sexually explicit or violent material. - - Posting (or threatening to post) other people's personally identifying - information ("doxing"). - - Sharing private content, such as emails sent privately or non-publicly, or - unlogged forums such as IRC channel history, without the sender's consent. - - Personal insults, especially those using racist, sexist, or ableist terms. - - Intentional or repeated misgendering of participants who have explicitly - requested to be addressed by specific pronouns. - - Unwelcome sexual attention. - - Excessive profanity. Please avoid swearwords; people differ greatly in - their sensitivity to swearing. - - Repeated harassment of others. In general, if someone asks you to stop, - then stop. - - Advocating for, or encouraging, any of the above behaviour. - -Diversity statement -=================== - -The kikuchipy project welcomes and encourages participation by everyone. We are -committed to being a community that everyone enjoys being part of. Although we -may not always be able to accommodate each individual's preferences, we try our -best to treat everyone kindly. - -No matter how you identify yourself or how others perceive you: we welcome you. -Though no list can hope to be comprehensive, we explicitly honour diversity in: -age, culture, ethnicity, genotype, gender identity or expression, language, -national origin, neurotype, phenotype, political beliefs, profession, race, -religion, sexual orientation, socioeconomic status, subculture and technical -ability, to the extent that these do not conflict with this code of conduct. - -Though we welcome people fluent in all languages, kikuchipy development is -conducted in English. - -Standards for behaviour in the kikuchipy community are detailed in the Code of -Conduct above. Participants in our community should uphold these standards in -all their interactions and help others to do so as well (see next section). - -Reporting guidelines -==================== - -We know that it is painfully common for internet communication to start at or -devolve into obvious and flagrant abuse. We also recognize that sometimes people -may have had a bad day, or be unaware of some of the guidelines in this Code of -Conduct. Please keep this in mind when deciding how to respond to a breach of -this Code. - -For clearly intentional breaches, report those to the Code of Conduct Committee -(see below). For possibly unintentional breaches, you may reply to the person -and point out this Code of Conduct (either in public or in private, whatever is -most appropriate). If you would prefer not to do that, please feel free to -report to the code of conduct committee directly, or ask the committee for -advice, in confidence. - -You can report issues to the kikuchipy Code of Conduct Committee, at -kikuchipy-conduct@googlegroups.com. Currently, the committee consists of: - -* `Håkon Wiik Ånes `_ (chair) -* `Tina Bergh `_ - -Incident reporting resolution & Code of Conduct enforcement -=========================================================== - -*This section summarizes the most important points, more details can be found -in* :doc:`report_handling_manual`. - -We will investigate and respond to all complaints. The kikuchipy Code of Conduct -Committee will protect the identity of the reporter, and treat the content of -complaints as confidential (unless the reporter agrees otherwise). - -In case of severe and obvious breaches, e.g. personal threat or violent, -sexist or racist language, we will immediately disconnect the originator from -kikuchipy communication channels; please see the manual for details. - -In cases not involving clear severe and obvious breaches of this code of -conduct, the process for acting on any received code of conduct violation report -will be: - -1. acknowledge report is received - -2. reasonable discussion/feedback - -3. mediation (if feedback didn't help, and only if both reporter and reportee - agree to this) - -4. enforcement via transparent decision (see :ref:`resolutions`) by the Code of - Conduct Committee - -The committee will respond to any report as soon as possible, and at most within -72 hours. - -Endnotes -======== - -We are thankful to the groups behind the following documents, from which we drew -content and inspiration: - -* `napari Code of Conduct `_ -* `NumPy Code of Conduct `_ +.. include:: ../CODE_OF_CONDUCT.rst \ No newline at end of file diff --git a/doc/contributing.rst b/doc/contributing.rst index 32f7e52d..1777ba46 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -1,294 +1,3 @@ -============ -Contributing -============ +.. This is a stub, see the top level CONTRIBUTING.rst file for the contributing guide. -kikuchipy is a community maintained project. We welcome contributions in the form of bug -reports, documentation, code, feature requests, and more. The source code is hosted on -`GitHub `_. These guidelines provide resources on -how best to contribute. - -.. tip:: - - This guide can look intimidating to people who want to contribute, but have limited - experience with tools like ``git``, ``pytest``, and ``sphinx``. The shortest route - to start contributing is to create a GitHub account and explain what you want to do - `in an issue `_. - -This project follows the `all-contributors -`_ specification. - -Questions, comments, and feedback -================================= - -Have a question, comment, suggestion 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. We also have a -`Gitter chat `_. - -Code of Conduct -=============== - -kikuchipy has a :doc:`Code of Conduct ` that should be honoured by -everyone who participates in the kikuchipy community. - -.. _setting-up-a-development-installation: - -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 kp-dev - conda activate kp-dev - -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 -``black``. - -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 -============== - -If you want to add a new feature, branch off of the ``develop`` branch, and when you -want to fix a bug, branch off of ``main`` instead. - -To create a new feature branch that tracks the upstream development branch:: - - git checkout develop -b your-awesome-feature-name upstream/develop - -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 -============================== - -If you are adding a new feature, make sure to merge ``develop`` into your feature -branch. If you are fixing a bug, merge ``main`` into your bug fix branch instead. - -To update a feature branch, switch to the ``develop`` branch:: - - git checkout develop - -Fetch changes from the upstream branch and update ``develop``:: - - git pull upstream develop --tags - -Update your feature branch:: - - git checkout your-awesome-feature-name - git merge develop - -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 -``develop`` branch for new features and ``main`` branch for bug fixes. 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 ``()`` for functions and methods. -- 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. -- The Furo Sphinx theme displays the documentation in a light or dark theme, depending - on the browser/OS setting. It is important to make sure the documentation is readable - with both themes. This means explicitly printing the signal axes manager, like - ``print(s.axes_manager)``, and displaying all figures with a white background for axes - labels and ticks and figure titles etc. to be readable. - -In general, we run all notebooks every time the documentation is built with Sphinx, to -ensure that all notebooks are compatible with the current API at all times. This is -important! For computationally expensive notebooks however, we store the cell outputs so -the documentation doesn't take too long to build, either by us locally or the Read The -Docs GitHub action. To check that the notebooks with cell outputs stored are compatible -with the current API as well, we run a scheduled GitHub Action every Monday morning -which checks that the notebooks run OK and that they produced the same output now as -when they were last executed. We use `nbval `_ -for this. - -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 :mod:`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. - -To run only a specific test function or class, .e.g the ``TestEBSD`` class:: - - pytest -k TestEBSD - -This is useful when you only want to run a specific test and not the full test suite, -e.g. when you're creating or updating a test. But remember to run the full test suite -before pushing! - -Docstring examples are tested `with pytest -`_ as well:: - - pytest --doctest-modules --ignore-glob=kikuchipy/*/tests - -Tips for writing tests of Numba decorated functions: - -- A Numba decorated function `numba_func()` is only covered if it is called in the test - as `numba_func.py_func()`. -- Always test a Numba decorated function calling `numba_func()` directly, in addition to - `numba_func.py_func()`, because the machine code function might give different results - on different OS with the same Python code. See `this issue for a case where this - happened `_. - -Adding data to the data module -============================== - -Test data for user guides and tests are included in the :mod:`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 `) 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. -:func:`~kikuchipy.data.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 re-download 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`. - -Improving performance -===================== -When we write code, it's important that we (1) get the correct result, (2) don't fill up -memory, and (3) that the computation doesn't take too long. To keep memory in check, we -should use `Dask `_ wherever possible. To speed up -computations, we should use `Numba `_ wherever -possible. - -Continuous integration (CI) -=========================== - -We use `GitHub Actions `_ to ensure that -kikuchipy can be installed on Windows, macOS and Linux (Ubuntu). After a successful -installation of the package, the CI server runs the tests. After the tests return no -errors, code coverage is reported to `Coveralls -`_. Add "[skip ci]" or to a -commit message to skip this workflow on any commit to a pull request, as explained +.. include:: ../CONTRIBUTING.rst \ No newline at end of file