Add JOSS paper for submission

.github/workflows/draft-pdf.yml

@@ -0,0 +1,25 @@
+on:
+  push:
+    paths:
+      - paper.md
+      - paper.bib
+      - architecture.png
+  pull_request:
+    paths:
+      - paper.md
+      - paper.bib
+      - architecture.png
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Draft PDF
+    steps:
+      - uses: actions/checkout@v4
+      - uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+      - uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          path: paper.pdf

CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: policyengine
+version: 3.4.4
+date-released: "2026-04-13"
+url: "https://github.com/PolicyEngine/policyengine.py"
+abstract: "An open-source Python package that provides a common analysis layer for tax-benefit microsimulation across the US and the UK."
+license: AGPL-3.0
+authors:
+  - family-names: Ghenis
+    given-names: Max
+    orcid: "https://orcid.org/0000-0002-1335-8277"
+    affiliation: PolicyEngine
+  - family-names: Ahmadi
+    given-names: Vahid
+    orcid: "https://orcid.org/0009-0004-1093-6272"
+    affiliation: PolicyEngine
+  - family-names: Woodruff
+    given-names: Nikhil
+    orcid: "https://orcid.org/0009-0009-5004-4910"
+    affiliation: PolicyEngine
+  - family-names: Makarchuk
+    given-names: Pavel
+    orcid: "https://orcid.org/0009-0003-4869-7409"
+    affiliation: PolicyEngine
+keywords:
+  - microsimulation
+  - tax
+  - benefit
+  - public policy
+  - Python
+repository-code: "https://github.com/PolicyEngine/policyengine.py"

CODE_OF_CONDUCT.md

@@ -0,0 +1,64 @@
+# Contributor covenant code of conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hello@policyengine.org. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

Makefile

@@ -9,7 +9,7 @@ docs-serve:
 	quarto preview docs
 
 install:
-	uv pip install -e .[dev]
+	uv pip install -e ".[dev]"
 
 format:
 	ruff format .

changelog.d/joss-paper.added.md

@@ -0,0 +1 @@
+Added JOSS paper (paper.md and paper.bib) for submission to the Journal of Open Source Software.

examples/paper_repro_uk.py

@@ -1,7 +1,8 @@
-"""Reproduce the UK policy-reform analysis used in the JOSS paper draft.
+"""Reproduce a UK policy-reform analysis for the JOSS paper.
 
-This script uses the same reform shown in `paper.md`, but adds the missing
-dataset setup so it can run end-to-end from a fresh checkout.
+This script demonstrates the population-level workflow described in the paper,
+using a UK reform (raising the personal allowance). The paper's inline code
+example uses a US reform; this script complements it with the UK equivalent.
 
 Run:
     uv run --python 3.14 --extra uk python examples/paper_repro_uk.py