Prepare 1.0.1 release (#26)

.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:
 <!--- Go over all the following points and make sure they have all been completed -->

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.

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: [email protected].
+We welcome your feedback and feature requests for the Data Analytics Framework for XDMoD via email: [email protected].
 
 ## Support
 For support, please see [this page](https://open.xdmod.org/support.html). If you email for support, please include the following:

docs/developing.md

@@ -1,60 +1,97 @@
-# 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 `<token>` with your token.
     ```
     XDMOD_API_TOKEN=<token>
     ```
 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`.

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 =

xdmod_data/__version__.py

@@ -1,2 +1,2 @@
 __title__ = 'xdmod-data'
-__version__ = '1.0.1-rc.1'
+__version__ = '1.0.1'