From 814f842646a100fa008bfc25a2809fa83423c95b Mon Sep 17 00:00:00 2001 From: Rodney Garnett <160431998+RodneyCodess@users.noreply.github.com> Date: Fri, 27 Sep 2024 13:57:30 -0400 Subject: [PATCH] Prepare 1.0.1 release (#26) --- .github/PULL_REQUEST_TEMPLATE.md | 1 + CHANGELOG.md | 15 ++++- README.md | 16 ++++- docs/developing.md | 109 +++++++++++++++++++++---------- setup.cfg | 6 +- xdmod_data/__version__.py | 2 +- 6 files changed, 103 insertions(+), 46 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9c7cbddd..c8f84986 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -21,6 +21,7 @@ - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) +- [ ] Release preparation ## Checklist: diff --git a/CHANGELOG.md b/CHANGELOG.md index 238d4ac2..3867132f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,22 @@ # xdmod-data Changelog -## Main development branch +## v1.0.1 (2024-09-27) + +This release has bug fixes, performance improvements, and updates for compatibility, tests, and documentation. + +- Add borders to README images ([\#12](https://github.com/ubccr/xdmod-data/pull/12)). +- Create `PULL_REQUEST_TEMPLATE.md` ([\#13](https://github.com/ubccr/xdmod-data/pull/13)). +- Add types of changes to pull request template ([\#15](https://github.com/ubccr/xdmod-data/pull/15)). +- Add Changelog ([\#17](https://github.com/ubccr/xdmod-data/pull/17)). - Update tests and testing instructions ([\#14](https://github.com/ubccr/xdmod-data/pull/14)). - Remove limit on number of results returned from `get_filter_values()` ([\#21](https://github.com/ubccr/xdmod-data/pull/21)). -- Add a "Feedback / Feature Requests" section to the README ([\#22](https://github.com/ubccr/xdmod-notebooks/pull/22)). +- Add citation for the DAF paper ([\#23](https://github.com/ubccr/xdmod-data/pull/23)). +- Add a "Feedback / Feature Requests" section to the README ([\#22](https://github.com/ubccr/xdmod-data/pull/22)). - Improve performance of validation of filters and raw fields ([\#18](https://github.com/ubccr/xdmod-data/pull/18)). - Fix bug with trailing slashes in `xdmod_host` ([\#24](https://github.com/ubccr/xdmod-data/pull/24)). - Use streaming for raw data requests ([\#19](https://github.com/ubccr/xdmod-data/pull/19)). - Specify minimum version numbers for dependencies ([\#25](https://github.com/ubccr/xdmod-data/pull/25)). ## v1.0.0 (2023-07-21) -- Initial release. + +Initial release. diff --git a/README.md b/README.md index 9aca07db..5a52ee06 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,22 @@ # xdmod-data -As part of the [XDMoD](https://open.xdmod.org) Data Analytics Framework, this Python package provides API access to the data warehouse of an instance of XDMoD version ≥10.5. +As part of the Data Analytics Framework for [XDMoD](https://open.xdmod.org), this Python package provides API access to the data warehouse of instances of Open XDMoD version ≥10.5. The package can be installed from PyPI via `pip install xdmod-data`. -It has dependencies on [NumPy](https://pypi.org/project/numpy/), [Pandas](https://pypi.org/project/pandas/), [Plotly](https://pypi.org/project/plotly/), and [Requests](https://pypi.org/project/requests/). +Existing installations can be upgraded via `pip install --upgrade xdmod-data`. + +The package has dependencies on [NumPy](https://pypi.org/project/numpy/), [Pandas](https://pypi.org/project/pandas/), [Plotly](https://pypi.org/project/plotly/), and [Requests](https://pypi.org/project/requests/). Example usage is documented through Jupyter notebooks in the [xdmod-notebooks](https://github.com/ubccr/xdmod-notebooks) repository. +## Compatibility with Open XDMoD +Specific versions of this package are compatible with specific versions of Open XDMoD as indicated in the table below. + +| `xdmod-data` version | Open XDMoD versions | +| -------------------- | ------------------- | +| 1.0.1 | 11.0.x, 10.5.x | +| 1.0.0 | 10.5.x | + ## API Token Access Use of the Data Analytics Framework requires an API token. To obtain an API token, follow the steps below to obtain an API token from the XDMoD portal. @@ -39,7 +49,7 @@ Use of the Data Analytics Framework requires an API token. To obtain an API toke **Note:** If you lose your token, simply delete it and generate a new one. ## Feedback / Feature Requests -We welcome your feedback and feature requests for the XDMoD Data Analytics Framework via email: ccr-xdmod-help@buffalo.edu. +We welcome your feedback and feature requests for the Data Analytics Framework for XDMoD via email: ccr-xdmod-help@buffalo.edu. ## Support For support, please see [this page](https://open.xdmod.org/support.html). If you email for support, please include the following: diff --git a/docs/developing.md b/docs/developing.md index 27488560..1d637043 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -1,20 +1,22 @@ -# Testing the code +# Instructions for developers + +## Testing the code 1. Start up a virtual environment, e.g.: ``` - $ env_dir=~/xdmod-data-test-env - $ python3 -m venv ${env_dir} - $ source ${env_dir}/bin/activate + python3 -m venv ~/xdmod-data-test-env + source ~/xdmod-data-test-env/bin/activate ``` + Your command prompt should now start with `(xdmod-data-test-env)`. 1. Install your local development copy of `xdmod-data` in editable mode: ``` - (env) $ python3 -m pip install --force-reinstall -e /path/to/your/xdmod-data + python3 -m pip install --force-reinstall -e /path/to/your/xdmod-data ``` 1. Install `python-dotenv` and `pytest`: ``` - (env) $ python3 -m pip install --upgrade python-dotenv pytest + python3 -m pip install --upgrade python-dotenv pytest ``` 1. Create an empty file in your home directory at `~/.xdmod-data-token` with permissions set to 600. -1. With an [https://xdmod.access-ci.org](ACCESS XDMoD) account with "User" as the Top Role, create an API token if you do not already have one (sign in and click My Profile -> API Token). +1. With an [ACCESS XDMoD](https://xdmod.access-ci.org) account with "User" as the Top Role, create an API token if you do not already have one (sign in and click My Profile -> API Token). 1. Add the following line to the file `~/.xdmod-data-token`, replacing `` with your token. ``` XDMOD_API_TOKEN= @@ -22,39 +24,74 @@ 1. Change directories to your local development copy of `xdmod-data`. 1. Run the following command and make sure all the tests pass: ``` - (env) $ pytest -vvs -o log_cli=true tests/ + pytest -vvs -o log_cli=true tests/ ``` 1. Downgrade to the minimum version of the dependencies. Replace the version numbers below with the values from `setup.cfg`. ``` - (env) $ python3 -m pip install --force-reinstall numpy==1.23.0 pandas==1.5.0 plotly==5.8.0 requests==2.19.0 + python3 -m pip install --force-reinstall numpy==1.23.0 pandas==1.5.0 plotly==5.8.0 requests==2.19.0 ``` -1. Run the following command again and make sure all the tests pass (Deprecation warnings in `urllib3` are Ok). +1. Run the following command again and make sure all the tests pass (Deprecation warnings in `urllib3` are OK). ``` - (env) $ pytest -vvs -o log_cli=true tests/ + pytest -vvs -o log_cli=true tests/ ``` -# Developing a new version -1. Make sure the version number is updated in `xdmod_data/__version__.py`. -1. Create a Pull Request for the new version. -# Distributing the new version to PyPI -After the Pull Request is approved, follow these steps in the `xdmod-data` root directory: -1. Start up a virtual environment, e.g.: - ``` - $ env_dir=~/xdmod-data-build-env - $ python3 -m venv ${env_dir} - $ source ${env_dir}/bin/activate - ``` -1. Make sure the required packages are installed: - ``` - (env) $ python3 -m pip install --upgrade pip build setuptools twine - ``` -1. Build the built distribution: - ``` - (env) $ python3 -m build --wheel - ``` -1. Upload the built distribution to PyPI, e.g., for version 1.0.0-beta1: - ``` - (env) $ version=1.0.0b1 - (env) $ twine upload dist/xdmod_data-${version}-py3-none-any.whl - ``` - Enter your PyPI username and password. +## Releasing a new version +1. Make a new branch of `xdmod-data` and: + 1. Make sure the version number is updated in `xdmod_data/__version__.py`. + 1. Update the Open XDMoD compatibility matrix in the `README.md`. + 1. Update `CHANGELOG.md` to change "Main development branch" to, e.g., `v1.0.1 (2024-06-XX)`. + 1. Create a Pull Request for the new version. +1. After the Pull Request is approved (but not merged yet), follow these steps in a cloned copy of the branch: + 1. Start up a virtual environment, e.g.: + ``` + python3 -m venv ~/xdmod-data-build-env + source ~/xdmod-data-build-env/bin/activate + ``` + Your command prompt should now start with `(xdmod-data-build-env)`. + 1. Make sure the required packages are installed: + ``` + python3 -m pip install --upgrade pip build setuptools twine + ``` + 1. Build the built distribution: + ``` + python3 -m build --wheel + ``` + 1. Validate `setup.cfg`, e.g., for version 1.0.0-beta1: + ``` + version=1.0.0b1 + twine check dist/xdmod_data-${version}-py3-none-any.whl + ``` + Make sure you receive `PASSED`. + 1. Upload the built distribution to TestPyPI: + ``` + twine upload --repository testpypi dist/xdmod_data-${version}-py3-none-any.whl + ``` + Enter your TestPyPI API token. + 1. Go to https://test.pypi.org/project/xdmod-data and confirm that everything looks right. + 1. Go to https://test.pypi.org/manage/project/xdmod-data/releases/ and: + 1. In the `Options` menu next to the release, click `Delete`. + 1. Type the version number in the box. + 1. Click `Delete release`. + 1. Upload the built distribution to PyPI: + ``` + twine upload dist/xdmod_data-${version}-py3-none-any.whl + ``` + Enter your PyPI username and password. + 1. Go to https://pypi.org/project/xdmod-data and confirm the new version is the latest release. +1. Update the date of the release in `CHANGELOG.md` and commit it to the Pull Request. +1. Merge the Pull Request. +1. Go to [create a new release on GitHub](https://github.com/ubccr/xdmod-data/releases/new) and: + 1. Click `Choose a tag`. + 1. Type in a tag similar to `v1.0.0` and choose `Create new tag`. + 1. Make the release title the same as the tag name (e.g., `v1.0.0`). + 1. Where it says `Describe this release`, paste in the contents of the release's section in `CHANGELOG.md`. + 1. Where it says `Attach binaries`, attach the built distribution that was uploaded to PyPI. + 1. Click `Publish release`. + +## After release + +1. Make a new branch of `xdmod-data` and: + 1. Make sure the version number is updated in `xdmod_data/__version__.py` to a beta release of the next version, e.g., `1.0.1-beta.1`. + 1. Update `CHANGELOG.md` to add a section at the top called `Main development branch`. + 1. Create a Pull Request for the new version. + 1. Once the Pull Request is approved, merge it into `main`. diff --git a/setup.cfg b/setup.cfg index 9fa7fab0..5a7b303d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,10 +1,10 @@ [metadata] name = xdmod-data version = attr: xdmod_data.__version__ -author = Aaron Weeden, Joseph P. White +author = Aaron Weeden, Joseph P. White, Rodney Garnett maintainer = Aaron Weeden, Joseph P. White -description = Python package for XDMoD data access -long_description = file: README.md +description = Python package for Open XDMoD data access +long_description = See the [README](https://github.com/ubccr/xdmod-data?tab=readme-ov-file#xdmod-data) for instructions on use. long_description_content_type = text/markdown license_files = LICENSE project_urls = diff --git a/xdmod_data/__version__.py b/xdmod_data/__version__.py index 9110dce3..09869ff8 100644 --- a/xdmod_data/__version__.py +++ b/xdmod_data/__version__.py @@ -1,2 +1,2 @@ __title__ = 'xdmod-data' -__version__ = '1.0.1-rc.1' +__version__ = '1.0.1'