generated from neutrons/python_project_template
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
7 changed files
with
281 additions
and
119 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| .. _coding_standards: | ||
|
|
||
| ============ | ||
| Contributing | ||
| ============ | ||
|
|
||
| We welcome contributions to the project. Please read the following guidelines before | ||
| submitting a pull request. | ||
|
|
||
| All contributors agree to the following: | ||
| - You have permission and any required rights to submit your contribution. | ||
| - Your contribution is provided under the license of this project and may be redistributed as such. | ||
| - All contributions to this project are public. | ||
|
|
||
| All contributions must be | ||
| `"signed off" in the commit <https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff>`_ | ||
| log and by doing so you agree to the above. | ||
|
|
||
| Getting access to the main project | ||
| ---------------------------------- | ||
|
|
||
| Direct commit access to the project is currently restricted to core developers. | ||
| All other contributions should be done through pull requests using the standard github mechanisms. | ||
|
|
||
| ============= | ||
| Pull Requests | ||
| ============= | ||
|
|
||
| * All pull requests should be made against the ``next`` branch. | ||
| * All changes made require associated tests and should follow :ref:`testing guidelines <testing>`. | ||
| * Developers should run the pre-commit hooks locally *before* submitting a pull request. | ||
| * Pull requests do not currently run the tests that require the garnet-data submodule. Developers should run these tests locally *before* submitting a pull request. | ||
| * If applicable, the pull request should include updates to the :ref:`documentation <documentation>`. | ||
| * All pull requests should include any information required to test the changes. This may include: | ||
|
|
||
| * A description of the changes | ||
| * A description of how to test the changes | ||
| * Any relevant data or scripts required to test the changes | ||
|
|
||
| A simple example of this workflow would be as follows: | ||
|
|
||
| .. code-block:: sh | ||
| git checkout -b my_new_feature | ||
| # Write Tests for your new feature | ||
| python -m pytest # New tests should fail | ||
| # Write code to make the tests pass | ||
| python -m pytest # All tests should pass | ||
| # update the documentation (if applicable) | ||
| git add <files> | ||
| git commit -m "My new feature" # pre-commit will run here | ||
| git push -u origin my_new_feature | ||
| Then, go to the `github page <https://github.com/neutrons/garnet/>`_ for the repository and create a new pull request from the ``my_new_feature`` branch to the ``next`` branch. | ||
|
|
||
| ================ | ||
| Coding Standards | ||
| ================ | ||
|
|
||
| A few notes on coding standards: | ||
|
|
||
| * Variable and function names should be descriptive and follow the ``lower_case_with_underscores`` convention. | ||
| * All code will be checked and formatted using `ruff <https://docs.astral.sh/ruff/rules/>`_. | ||
| * Docstrings should be used to document all functions, classes, and Modules. | ||
| * Pre-commit hooks are configured to run for every PR, and can be run locally on every commit. | ||
|
|
||
| Pre-commit | ||
| ---------- | ||
|
|
||
| Pre-commit is a tool that is used to ensure that all code is formatted and linted before being committed. | ||
|
|
||
| Install pre-commit | ||
| ++++++++++++++++++ | ||
|
|
||
| pre-commit can be installed using the following command: | ||
|
|
||
| .. code-block:: sh | ||
| pre-commit install | ||
| You should only need to do this once. pre-commit will now run on every commit. | ||
|
|
||
| Run pre-commit manually | ||
| +++++++++++++++++++++++ | ||
|
|
||
| The following command will run pre-commit on all staged changes: | ||
|
|
||
| .. code-block:: sh | ||
| pre-commit | ||
| To run pre-commit on all files in the repository, run the following command: | ||
|
|
||
| .. code-block:: sh | ||
| pre-commit run --all | ||
| More information on pre-commit can be found in the `pre-commit documentation <https://pre-commit.com/>`_. | ||
|
|
||
|
|
||
| ======================== | ||
| Documentation Guidelines | ||
| ======================== | ||
|
|
||
| .. _documentation: | ||
|
|
||
| Updating the Documentation | ||
| -------------------------- | ||
| This project uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_ to generate documentation and is updated with every pull request. | ||
| The documentation is a combination of pages written in `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ and | ||
| docstrings pulled from the code. | ||
| A simple guide to updating documentation in Garnet can be found `here <https://github.com/neutrons/garnet/blob/next/docs/README.md>`_. | ||
|
|
||
| Building the Documentation | ||
| -------------------------- | ||
| To build the documentation locally, run the following commands from the root of the repository: | ||
|
|
||
| .. code-block:: sh | ||
| cd docs | ||
| make clean | ||
| make html | ||
| The documentation will be built in the ``docs/_build/html`` directory. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| .. _testing: | ||
|
|
||
| ======= | ||
| Testing | ||
| ======= | ||
|
|
||
| The project contains testing infrastructure in the tests/ folder: | ||
| * data/ : It contains the test data. Small data files can be included in this | ||
| directory. For large data files, there is a subfolder garner-data that is connected to a gitlfs data | ||
| repo in gitlab as a submodule: https://code.ornl.gov/sns-hfir-scse/infrastructure/test-data/garnet-data | ||
| * tabs/ : Tests are organized into folders for every page: | ||
|
|
||
| * home/ | ||
| * order_param/ | ||
| * peak_integr/ | ||
| * recp_space/ | ||
| * ub_peak_find\/ | ||
|
|
||
| In every page-tab directory the tests are furtherd arranged in MVP-based filesystem structure: | ||
|
|
||
| * models/ | ||
| * views/ | ||
| * presenter/ | ||
|
|
||
| * utility/ : It contains tests for code elements that are shared among pages and belong to the corresponding file folder (utility/). | ||
| * workflows/ : It contains tests with code that span among pages to test full reduction workflows. | ||
|
|
||
| Writing Tests | ||
| ````````````` | ||
| We strongly encourage adopting a Test-Driven Development (TDD) approach throughout the development process. By writing tests before implementing | ||
| features, we promote code reliability, maintainability, and faster debugging. Embrace TDD as a best practice to enhance the overall quality of our project. | ||
| The general approach is to write tests for every function and method in the code. The tests should cover all possible input combinations and edge cases. | ||
|
|
||
| The tests are written using the `pytest <https://docs.pytest.org/>`_ framework to allow for automated testing. The test files are named `test_*.py` and are | ||
| placed in the corresponding directory of the code they are testing. | ||
|
|
||
| Tests that use the garnet-data submodule, will need to be configured for github runners (TBD). | ||
| Additionally, the `pytest marker <https://docs.pytest.org/en/8.0.x/reference/reference.html#custom-marks>`_ ``datarepo`` is used to skip tests that require | ||
| garnet-data submodule to be present. | ||
|
|
||
| Running Tests | ||
| ````````````` | ||
| The tests can be run using the `pytest <https://docs.pytest.org/>`_ framework. The tests can be run in the garnet conda environment. | ||
| The following instructions assume that the current working directory is the root of the garnet repository and that the garnet conda environment is activated. | ||
|
|
||
| To run all tests: | ||
|
|
||
| .. code-block:: sh | ||
| python -m pytest | ||
| To run a specific test: | ||
|
|
||
| .. code-block:: sh | ||
| python -m pytest path/to/test_file.py | ||
| To run a specific test function: | ||
|
|
||
| .. code-block:: sh | ||
| python -m pytest path/to/test_file.py::test_function | ||
| To run tests that require the garnet-data submodule: | ||
|
|
||
| .. code-block:: sh | ||
| python -m pytest -m datarepo | ||
| ===================== | ||
| Testing a specific PR | ||
| ===================== | ||
|
|
||
| Checkout to the PR by following the Pull-Request instructions: | ||
|
|
||
| .. code-block:: sh | ||
| conda activate <garnet_environment> | ||
| cd /path/to/my/local/garnet/repo/ | ||
| git fetch origin pull/<PULL_REQUEST_NUMBER>/head:pr<PULL_REQUEST_NUMBER> | ||
| git switch pr<PULL_REQUEST_NUMBER> | ||
| #run tests | ||
| python -m pytest <item_to_test> | ||
| #and/or start garnet | ||
| garnet | ||
| To test a specific Mantid build and/or version in another conda environment, garnet can be installed in that environment: | ||
|
|
||
| .. code-block:: sh | ||
| conda activate <mantid_environment> | ||
| #in case of a mantid build, else skip | ||
| ./bin/AddPythonPath.py | ||
| cd /path/to/my/local/garnet/repo/ | ||
| git fetch origin pull/<PULL_REQUEST_NUMBER>/head:pr<PULL_REQUEST_NUMBER> | ||
| git switch pr<PULL_REQUEST_NUMBER> | ||
| python -m pip install -e . | ||
| #run tests | ||
| python -m pytest <item_to_test> | ||
| #and/or start garnet | ||
| garnet |
Oops, something went wrong.