From 3b1d327f5676e76fc0cf32dc5c02747612c162b4 Mon Sep 17 00:00:00 2001 From: Dmitri Gavrilov Date: Wed, 2 Aug 2023 13:10:49 -0400 Subject: [PATCH 1/4] STY: fixed style for flake8 --- bluesky_queueserver/manager/tests/test_conversions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bluesky_queueserver/manager/tests/test_conversions.py b/bluesky_queueserver/manager/tests/test_conversions.py index 0d583fc6..93e2aedb 100644 --- a/bluesky_queueserver/manager/tests/test_conversions.py +++ b/bluesky_queueserver/manager/tests/test_conversions.py @@ -162,7 +162,7 @@ def test_read_cell_parameter(val_in, val_out, val_type, success, errmsg): val_result = _read_cell_parameter(val_in) assert val_result == val_out if val_type: - assert type(val_result) == val_type + assert isinstance(val_result, val_type) else: with pytest.raises(Exception, match=errmsg): _read_cell_parameter(val_in) From 33bd78e6fdb21472b24ed70075eb0539c6f77c08 Mon Sep 17 00:00:00 2001 From: Dmitri Gavrilov Date: Wed, 2 Aug 2023 13:55:42 -0400 Subject: [PATCH 2/4] CI: update pre-commit versions --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c54fb967..8f8ca4be 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -8,11 +8,11 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/ambv/black - rev: 23.3.0 + rev: 23.7.0 hooks: - id: black - repo: https://github.com/pycqa/flake8 - rev: 6.0.0 + rev: 6.1.0 hooks: - id: flake8 - repo: https://github.com/pycqa/isort From 87b14a1d45c1534b3dce36f22fd88d551dddf4d1 Mon Sep 17 00:00:00 2001 From: Dmitri Gavrilov Date: Wed, 2 Aug 2023 14:48:52 -0400 Subject: [PATCH 3/4] DOC: notes for contributors --- docs/source/contributing.rst | 63 ++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + docs/source/installation.rst | 8 +++-- 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/source/contributing.rst diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 00000000..b85c0e21 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,63 @@ +============ +Contributing +============ + +Development Installation +------------------------ + +Install Redis and create Conda environment as described in :ref:`installation_steps`. + +Install the Queue Server in editable mode:: + + $ pip install -e . + +Install development dependencies:: + + $ pip install -r requirements-dev.txt + + +Setting up `pre-commit` +----------------------- + +`pre-commit`` package is installed as part of the development requirements. Install pre-commit +script by running :: + + $ pre-commit install + +Once installed, `pre-commit` will perform all the checks before each commit. As the new versions +of validation packages are released, the pre-commit script can be updated by running :: + + $ pre-commit autoupdate + + +Running Unit Tests Locally +-------------------------- + +The Queue Server must be tested separately with disabled IPython mode:: + + $ pytest -vvv + +or :: + + $ USE_IPYKERNEL=false pytest -vvv + +and enabled IPython mode:: + + $ USE_IPYKERNEL=true pytest -vvv + + +Running Unit Tests on GitHub +---------------------------- + +Execution of the full test suite on CI takes too long and causes major inconvenience, +therefore it is split into multiple groups (currently 3 groups) using `pytest-split` +package. Since the goal is to reduce the execution time of the longest group, the +splitting algorithm is calibrated based on execution time of the tests with enabled +IPython kernel mode (more tests, each test takes a little longer to execute). +Calibration is performed by running the script ``store_test_durations.sh`` locally, +which saves execution time for each test in the ```.test_durations`` file. The file then +has to be committed and pushed to the repository. + +`pytest-split` will automatically guess execution time for new tests that are not +listed in ``.test_durations`` file, so calibration may be needed rarely or after major +changes to the test suite and is expected to be performed by the package maintainers. diff --git a/docs/source/index.rst b/docs/source/index.rst index 49ad0344..d9f9857f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,6 +13,7 @@ Bluesky-QueueServer Documentation installation tutorials release_history + contributing Source Code on GitHub .. toctree:: diff --git a/docs/source/installation.rst b/docs/source/installation.rst index b75b459d..b00a8c14 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -7,26 +7,30 @@ System Requirements Supported Python versions: 3.7, 3.8, 3.9, 3.10, 3.11. +.. _installation_steps: + Installation Steps ------------------ * **Install Redis** - Skip this step if **Redis** is already installed. + Skip this step if **Redis** is already installed and running. Linux:: $ sudo apt install redis + $ sudo systemctl start redis Mac OS: See https://gist.github.com/tomysmile/1b8a321e7c58499ef9f9441b2faa0aa8. + * **Create Conda environment** It is recommended to install the Queue Server in Conda environment. A new environment can be created or already existing environment can be activated. The following example illustrates how to create - a new Conda environment with the name *queue_server* and Python 3.9 installed:: + a new Conda environment with the name *queue_server* and Python 3.10 installed:: $ conda create -n queue_server python=3.10 $ activate queue_server From 86eba4565b00bb1a95455946bc7ba1cd761721fb Mon Sep 17 00:00:00 2001 From: Dmitri Gavrilov Date: Wed, 2 Aug 2023 19:17:37 -0400 Subject: [PATCH 4/4] DOC: more notes for contributors --- docs/source/contributing.rst | 90 ++++++++++++++++++++++++++++++++++-- 1 file changed, 87 insertions(+), 3 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index b85c0e21..9c4dc01a 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -2,8 +2,92 @@ Contributing ============ -Development Installation ------------------------- +General Notes +------------- + +Getting Started +=============== + +* Make sure you have a `GitHub account `_. +* Submit a ticket for your issue, assuming one does not already exist. + + * Clearly describe the issue including steps to reproduce when it is a bug. + * Make sure you fill in the earliest version that you know has the issue. + +* Fork the repository on GitHub + + +Making Changes +============== + +* Create a topic branch from where you want to base your work. + + * This is usually the `main` branch. + * Only target release branches if you are certain your fix must be on that + branch. + * To quickly create a topic branch based on `main`; ``git checkout -b + my_branch_name main``. Please avoid working directly on the + `main` branch. + +* Make commits of logical units. +* Check for unnecessary whitespace with ``git diff --check`` before committing. +* Make sure your commit messages are in the proper format (see below) +* Make sure you have added the necessary tests for your changes. +* Run *all* the tests to assure nothing else was accidentally broken. + +Writing the commit message +========================== + +Commit messages should be clear and follow a few basic rules. Example:: + + ENH: add functionality X to bluesky.. + + The first line of the commit message starts with a capitalized acronym + (options listed below) indicating what type of commit this is. Then a blank + line, then more text if needed. Lines shouldn't be longer than 72 + characters. If the commit is related to a ticket, indicate that with + "See #3456", "See ticket 3456", "Closes #3456" or similar. + +Describing the motivation for a change, the nature of a bug for bug fixes +or some details on what an enhancement does are also good to include in a +commit message. Messages should be understandable without looking at the code +changes. + +Standard acronyms to start the commit message with are:: + + API: an (incompatible) API change + BLD: change related to building numpy + BUG: bug fix + CI : continuous integration + DEP: deprecate something, or remove a deprecated object + DEV: development tool or utility + DOC: documentation + ENH: enhancement + MNT: maintenance commit (refactoring, typos, etc.) + REV: revert an earlier commit + STY: style fix (whitespace, PEP8) + TST: addition or modification of tests + REL: related to releases + +The Pull Request +================ + +* Now push to your fork +* Submit a `pull request `_ to this branch. This is a start to the conversation. + +At this point you're waiting on us. We like to at least comment on pull requests within three business days +(and, typically, one business day). We may suggest some changes or improvements or alternatives. + +Hints to make the integration of your changes easy (and happen faster): + +* Keep your pull requests small +* Don't forget your unit tests +* All algorithms need documentation, don't forget the .rst file +* Don't take changes requests to change your code personally + + +Installation of the Queue Server for Development +------------------------------------------------ Install Redis and create Conda environment as described in :ref:`installation_steps`. @@ -60,4 +144,4 @@ has to be committed and pushed to the repository. `pytest-split` will automatically guess execution time for new tests that are not listed in ``.test_durations`` file, so calibration may be needed rarely or after major -changes to the test suite and is expected to be performed by the package maintainers. +changes to the test suite and should be left to the package maintainers.