Merge pull request #294 from plotly/update-contributing

Explain versioning system

.github/workflows/python-test.yml

@@ -97,6 +97,8 @@ jobs:
           npm run build
         timeout-minutes: 20
       - run: npm run lint
-      - run: |
+      - name: Run tests
+        run: |
           source .venv/bin/activate
-          pytest --headless
+          pytest --headless -k "not test_versioning"
+

.github/workflows/release.yml

@@ -24,6 +24,11 @@ jobs:
           curl -LsSf https://astral.sh/uv/install.sh | sh
           uv venv
         shell: bash
+      - name: Run all tests
+        run: |
+          source .venv/bin/activate
+          uv pip install ".[dev]"
+          pytest --headless
       - name: Generate distribution
         run: |
           source .venv/bin/activate

CONTRIBUTING.md

@@ -25,6 +25,20 @@ $ pip install -e .
 ```
 In development mode, Python uses the files in this directory when you import the package. So you can write a testing app in another folder, and whenever you change some code and rebuild the component here it will update in your testing app.
 
+### Versioning
+We follow a strict versioning system aligned with the underlying Ag Grid version, but also reserving the
+patch number for updates to the Dash grid.
+
+Specifically, Dash Ag Grid will always have the same _major_ and _minor_ version number as the Javascript Ag Grid package it is bundling, but it may not always have the same patch number.
+
+Ag Grid releases new major versions every 6-8 months, and minor versions every 4-6 weeks. Sometimes, Dash Ag Grid may introduce new changes that warrant a minor release according to [semver](https://semver.org/): For example, exposing a functional property of Ag Grid as a declarative property in Dash Ag Grid. In this case, we would wait for a new minor release of Ag Grid and bump the versions together.
+
+We may release out-of-band of Ag Grid when there are patches that we want to make available.
+
+As a user, you can always check the underlying Ag Grid version with `dash_ag_grid.grid_version` and the underlying Dash Ag Grid version with `dash_ag_grid.__version__`.
+
+For maintainers, when issuing new releases ensure that the version bump of Dash Ag Grid follows this convention. This can be verified after a build by using `npm run pre-flight-dag-version` or `python test_versioning.py`. This is validated during the `npm run dist`
+
 ### Create a production build
 
 Update the package version in `package.json` and `CHANGELOG.md` and ensure the changelog lists all the important updates. Then reinstall (so `package-lock.json` gets the new version) and rebuild:
@@ -35,8 +49,7 @@ npm run build
 
 Commit this - either via a PR or directly to the main branch. Then you can create source and wheel distributions in the generated `dist/` folder, after emptying out any previous builds:
 ```
-rm -rf dist build
-python setup.py sdist bdist_wheel
+npm run dist
 ```
 See [PyPA](https://packaging.python.org/guides/distributing-packages-using-setuptools/#packaging-your-project)
 for more information. At this point you can test the build. The best way is to make a virtual env in another directory, install the wheel you just built, and run one of the demo apps, something like:
@@ -57,7 +70,7 @@ Create a new distribution with:
 npm run dist
 ```
 
-It doesn't need to be tested extensively, just enough to know that the table loads with no errors and you've built the right version of the code. If the app looks good, use [`twine`](https://pypi.org/project/twine/) to upload these to PyPI:
+It doesn't need to be tested extensively, just enough to know that the grid loads with no errors and you've built the right version of the code. If the app looks good, use [`twine`](https://pypi.org/project/twine/) to upload these to PyPI:
 ```
 # back in the dash-ag-grid directory
 twine upload dist/*

package.json

@@ -13,6 +13,7 @@
     "main": "dash_ag_grid/dash_ag_grid.min.js",
     "scripts": {
         "pre-flight-version": "python test_version.py",
+        "pre-flight-dag-version": "python test_versioning.py",
         "prepublishOnly": "rimraf -rf lib && babel src --out-dir lib --copy-files --config-file ./.babelrc && rimraf --glob -rf lib/jl/ lib/*.jl",
         "build:js": "webpack --mode production",
         "build:backends": "dash-generate-components ./src/lib/components dash_ag_grid -p package-info.json --r-prefix '' --jl-prefix ''",
@@ -24,7 +25,7 @@
         "private::lint.eslint": "eslint src",
         "private::lint.prettier": "prettier src --list-different --ignore-path=.prettierignore",
         "lint": "run-s private::lint.*",
-        "dist": "npm run build && python setup.py sdist bdist_wheel"
+        "dist": "npm run build && run-s pre-flight-dag-version &&  python setup.py sdist bdist_wheel"
     },
     "author": "Plotly <[email protected]>",
     "license": "MIT",

test_versioning.py

@@ -0,0 +1,19 @@
+from packaging.version import parse
+import dash_ag_grid as dag
+
+
+"""
+Test that the major and minor versions of bundled Ag Grid align with
+the major and minor versions of the Python package.
+
+See CONTRIBUTING.md for more information on versioning this package.
+"""
+ag_version = parse(dag.grid_version)
+dash_ag_version = parse(dag.__version__)
+
+if not (ag_version.major == dash_ag_version.major and ag_version.minor == dash_ag_version.minor):
+    raise Exception("There is a version mismatch in DAG and AG-Grid, check your package.json and adjust")
+try:
+    print('DAG version and AG-Grid are in perfect harmony 🎉')
+except:
+    print('DAG version and AG-Grid are in perfect harmony :)')