From b51d1038934c458607bda23e87c1be6f4a1c35c8 Mon Sep 17 00:00:00 2001
From: Marcus Griffiths <44459040+marcusdgriff@users.noreply.github.com>
Date: Mon, 12 Oct 2026 19:02:37 -0500
Subject: [PATCH] Release PlantID Label Designer 1.0.0

- Bump the app to 1.0.0 and record it in the example layouts.
- Add citation details for the PlantID paper to CITATION.cff, the
  README, and the app footer, and state the license in the README.
- Add a changelog.
- Pin dependencies to tested versions and drop the unused qrcode and
  numpy requirements.
- Run the tests on GitHub Actions with Python 3.11 and 3.12.
- Fix the dev container, which looked for requirements.txt in the
  repository root and so never installed the app's dependencies.
---
 .devcontainer/devcontainer.json               |  2 +-
 .github/workflows/tests.yml                   | 27 +++++++++++++
 CHANGELOG.md                                  | 40 +++++++++++++++++++
 CITATION.cff                                  | 30 ++++++++++++++
 .../example_layout.json                       |  2 +-
 .../example_sheet_layout.json                 |  2 +-
 .../requirements.txt                          | 14 +++----
 .../streamlit_app.py                          |  7 +++-
 README.md                                     | 25 ++++++++++--
 9 files changed, 134 insertions(+), 15 deletions(-)
 create mode 100644 .github/workflows/tests.yml
 create mode 100644 CHANGELOG.md
 create mode 100644 CITATION.cff

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 44357a7..6179220 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -17,7 +17,7 @@
       ]
     }
   },
-  "updateContentCommand": "[ -f packages.txt ] && sudo apt update && sudo apt upgrade -y && sudo xargs apt install -y <packages.txt; [ -f requirements.txt ] && pip3 install --user -r requirements.txt; pip3 install --user streamlit; echo '✅ Packages installed and Requirements met'",
+  "updateContentCommand": "[ -f packages.txt ] && sudo apt update && sudo apt upgrade -y && sudo xargs apt install -y <packages.txt; pip3 install --user -r PlantID-LabelDesigner-streamlit/requirements.txt; echo '✅ Packages installed and Requirements met'",
   "postAttachCommand": {
     "server": "streamlit run PlantID-LabelDesigner-streamlit/streamlit_app.py --server.enableCORS false --server.enableXsrfProtection false"
   },
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..206fcec
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    defaults:
+      run:
+        working-directory: PlantID-LabelDesigner-streamlit
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: PlantID-LabelDesigner-streamlit/requirements.txt
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run tests
+        run: pytest
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..e01d86f
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to PlantID Label Designer are listed here. The app follows [semantic versioning](https://semver.org). Saved layout files have their own [schema version](README.md#versioning).
+
+## 1.0.0
+
+First stable release, accompanying the PlantID paper in the *International Journal of Phenomics*.
+
+### Added
+- Excel (`.xlsx`) data files, alongside CSV.
+- A one-page start screen: choose your data, then start from defaults, an example layout, or a saved layout.
+- One-click **Download labels PDF**, with problems that block export shown beforehand.
+- A first-sheet preview and a numbered alignment test page for sheet stock.
+- Warnings when text does not fit on a label (checked across every selected row), or when a QR code or barcode is too small to scan reliably.
+- A list of any columns a loaded layout refers to that are missing from the data.
+- A preset browser dialog with search that stays in view on small screens.
+- **Show advanced settings**, gathering the label border, spacing and offset adjustments, and wrap tags.
+- Citation information in the app, the README and `CITATION.cff`, and a label gallery in the README.
+- Automated tests on GitHub Actions.
+
+### Changed
+- Layout files use schema version 1, with descriptive field names. Schema 0 files are converted when loaded. Row ranges, filters, and the first label position are no longer saved in layouts.
+- QR codes use error correction level M (about 15% damage tolerance, previously 7%).
+- **Code offset from edge** is measured from the label edge for every barcode placement. Schema 0 layouts are adjusted on load so their output is unchanged.
+- Version warnings appear only when a layout's schema differs from the app's.
+- Dependencies are pinned to tested versions.
+
+### Fixed
+- Spreadsheet values are printed exactly as written: IDs keep leading zeros, whole numbers are not shown as `1.0`, and blank cells are not printed as `nan`.
+- CSV files saved by Excel on Windows load instead of crashing the app.
+- Barcodes beside text are drawn at the chosen width instead of up to 1.7× wider, and always in black.
+- Long text is clipped to its label instead of printing onto neighbouring labels.
+- Hidden settings loaded from a layout keep their values instead of reverting to defaults.
+- The Codespaces dev container installs the app's requirements.
+
+## 0.10
+
+- Text above, below, or on both sides of a barcode.
+- Wrap tags with a tear-off section for loop-lock stock.
+- Label size presets and sheet stock presets, and a first label position for partly used sheets.
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000..fade432
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use PlantID in your research, please cite the paper below."
+title: "PlantID Label Designer"
+abstract: "A Streamlit web application for designing and printing plant sample labels with QR codes or barcodes from a spreadsheet of unique plant identifiers."
+type: software
+version: 1.0.0
+license: MPL-2.0
+repository-code: "https://github.com/danforthcenter/PlantID"
+url: "https://plantid-label-designer.streamlit.app"
+keywords:
+  - plant phenotyping
+  - unique identifiers
+  - QR code
+  - barcode
+  - labels
+authors:
+  - family-names: Griffiths
+    given-names: Marcus
+  - family-names: Murphy
+    given-names: Katherine M.
+preferred-citation:
+  type: article
+  title: "PlantID: A Flexible Unique Identifier Framework for Plant Phenotyping"
+  authors:
+    - family-names: Griffiths
+      given-names: Marcus
+    - family-names: Murphy
+      given-names: Katherine M.
+  journal: "International Journal of Phenomics"
+  status: in-press
diff --git a/PlantID-LabelDesigner-streamlit/example_layout.json b/PlantID-LabelDesigner-streamlit/example_layout.json
index 96d6526..532697a 100644
--- a/PlantID-LabelDesigner-streamlit/example_layout.json
+++ b/PlantID-LabelDesigner-streamlit/example_layout.json
@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "app": "PlantID Label Designer",
-  "app_version": "0.10",
+  "app_version": "1.0.0",
   "layout": {
     "data": {
       "fields": [
diff --git a/PlantID-LabelDesigner-streamlit/example_sheet_layout.json b/PlantID-LabelDesigner-streamlit/example_sheet_layout.json
index 6cebf6d..29f4200 100644
--- a/PlantID-LabelDesigner-streamlit/example_sheet_layout.json
+++ b/PlantID-LabelDesigner-streamlit/example_sheet_layout.json
@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "app": "PlantID Label Designer",
-  "app_version": "0.10",
+  "app_version": "1.0.0",
   "layout": {
     "data": {
       "fields": [
diff --git a/PlantID-LabelDesigner-streamlit/requirements.txt b/PlantID-LabelDesigner-streamlit/requirements.txt
index e25d12a..7403f0e 100644
--- a/PlantID-LabelDesigner-streamlit/requirements.txt
+++ b/PlantID-LabelDesigner-streamlit/requirements.txt
@@ -1,8 +1,6 @@
-streamlit
-pandas
-numpy
-reportlab
-qrcode
-pillow
-pypdfium2
-openpyxl
+streamlit==1.56.0
+pandas==2.3.2
+reportlab==4.4.10
+pypdfium2==5.7.0
+pillow==11.3.0
+openpyxl==3.1.5
diff --git a/PlantID-LabelDesigner-streamlit/streamlit_app.py b/PlantID-LabelDesigner-streamlit/streamlit_app.py
index 38fab23..74335c1 100644
--- a/PlantID-LabelDesigner-streamlit/streamlit_app.py
+++ b/PlantID-LabelDesigner-streamlit/streamlit_app.py
@@ -60,7 +60,11 @@
     st.session_state.layout_widget_generation = 0
 
 APP_NAME = "PlantID Label Designer"
-APP_VERSION = "0.10"
+APP_VERSION = "1.0.0"
+CITATION = (
+    "Griffiths, M. and Murphy, K. M. PlantID: A Flexible Unique Identifier Framework for "
+    "Plant Phenotyping. International Journal of Phenomics (in press)."
+)
 TEMPLATE_VERSION = SCHEMA_VERSION
 
 PRINTER_TYPE_OPTIONS = [PRINTER_TYPE_SHEET, PRINTER_TYPE_LABEL]
@@ -325,6 +329,7 @@ def render_version_footer():
         "Source code and documentation: [github.com/danforthcenter/PlantID](https://github.com/danforthcenter/PlantID) "
         "— can be run locally if downloaded."
     )
+    st.caption(f"If you use PlantID in your research, please cite: {CITATION}")
 
     if not loaded_template:
         return
diff --git a/README.md b/README.md
index 7d6a009..5cd2cc2 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,13 @@ Run the app locally:
 ```bash
 streamlit run streamlit_app.py
 ```
+
+Run the tests:
+```bash
+pip install pytest
+pytest
+```
+
 ## Using the app
 
 1. **Choose your data**: upload a CSV or Excel (`.xlsx`) file with one row per plant or sample, or try the example dataset. Values are printed exactly as written, so IDs such as `00123` keep their leading zeros.
@@ -42,10 +49,10 @@ streamlit run streamlit_app.py
 
 | Version | Current |
 |---|---|
-| App | 0.10 |
+| App | 1.0.0 |
 | Layout schema | 1 |
 
-The **app version** reflects the overall release of PlantID Label Designer. The **layout schema version** tracks the structure of saved layout `.json` files and only increments when the format changes in a way older apps cannot read. Layouts saved with an older schema are converted automatically when loaded; save them again to update the file. The app warns if a layout uses a newer schema than it supports.
+The **app version** follows [semantic versioning](https://semver.org); changes are listed in the [changelog](CHANGELOG.md). The **layout schema version** tracks the structure of saved layout `.json` files and only increments when the format changes in a way older apps cannot read. Layouts saved with an older schema are converted automatically when loaded; save them again to update the file. The app warns if a layout uses a newer schema than it supports.
 
 ## Layout files
 
@@ -55,7 +62,7 @@ The **app version** reflects the overall release of PlantID Label Designer. The
 {
   "schema_version": 1,
   "app": "PlantID Label Designer",
-  "app_version": "0.10",
+  "app_version": "1.0.0",
   "layout": {
     "data": { "fields": ["Plant", "Geno"], "field_labels_enabled": false, "field_labels": {}, "split": { "enabled": false, ... } },
     "label": { "preset": "PR1MA 85 Tag", "width_mm": 33.0, "height_mm": 13.0, "display_units": "mm", "padding_mm": 2, "border": true },
@@ -71,3 +78,15 @@ The **app version** reflects the overall release of PlantID Label Designer. The
 ```
 
 Sizes are in millimetres. `label.preset` and `printer.sheet_stock` name a built-in preset, or are `null` for a custom size or spacing; the page size, margins and gaps are always saved so a sheet layout still prints if a preset is renamed. See [`example_layout.json`](PlantID-LabelDesigner-streamlit/example_layout.json) and [`example_sheet_layout.json`](PlantID-LabelDesigner-streamlit/example_sheet_layout.json) for complete files, and [`layout_schema.py`](PlantID-LabelDesigner-streamlit/layout_schema.py) for every field.
+
+## How to cite
+
+If you use PlantID in your research, please cite:
+
+> Griffiths, M. and Murphy, K. M. PlantID: A Flexible Unique Identifier Framework for Plant Phenotyping. *International Journal of Phenomics* (in press).
+
+GitHub's **Cite this repository** button provides this in APA and BibTeX formats from [`CITATION.cff`](CITATION.cff).
+
+## License
+
+PlantID Label Designer is released under the [Mozilla Public License 2.0](LICENSE).