Write JOSS paper draft for repository

JOSS_SUBMISSION_NOTES.md

@@ -0,0 +1,175 @@
+# JOSS Submission Notes for ObjectState
+
+This document provides guidance for preparing and submitting the ObjectState paper to the Journal of Open Source Software (JOSS).
+
+## Files Created
+
+1. **paper.md** - The main JOSS paper in markdown format
+2. **paper.bib** - Bibliography with all references cited in the paper
+3. **JOSS_SUBMISSION_NOTES.md** - This file with submission guidance
+
+## Before Submitting
+
+### 1. Update Author Information
+
+**CRITICAL**: Replace the placeholder ORCID in `paper.md`:
+
+```yaml
+authors:
+  - name: Tristan Simas
+    orcid: 0000-0000-0000-0000  # TODO: Replace with actual ORCID
+```
+
+- Get your ORCID at [https://orcid.org/](https://orcid.org/)
+- Update line 13 of `paper.md` with your actual ORCID number
+- If there are co-authors, add them to the authors section
+
+### 2. Verify Repository Requirements
+
+JOSS requires that your repository meets these criteria:
+
+- ✅ **Open source license**: MIT license present in LICENSE file
+- ✅ **Version control**: Git repository on GitHub
+- ✅ **Documentation**: ReadTheDocs documentation available
+- ✅ **Installation instructions**: Present in README.md
+- ⚠️ **Tagged release**: Ensure you have a tagged release (e.g., v0.1.0)
+- ⚠️ **Community guidelines**: Consider adding CONTRIBUTING.md if not present
+- ✅ **Tests**: Comprehensive test suite with 100% coverage
+- ⚠️ **Statement of need**: Included in paper.md
+
+### 3. Create a Tagged Release
+
+Before submitting to JOSS, create a release on GitHub:
+
+```bash
+git tag -a v0.1.0 -m "Initial JOSS submission"
+git push origin v0.1.0
+```
+
+Or use GitHub's web interface to create a release.
+
+### 4. Review Paper Content
+
+The paper includes:
+
+- **Summary**: Overview of ObjectState and its novel dual-axis inheritance model
+- **Statement of Need**: Explains why this software is needed and who the target audience is
+- **State of the Field**: Compares to existing configuration frameworks
+- **Implementation & Quality**: Details architecture, components, and quality assurance
+- **Example Usage**: Code example demonstrating dual-axis inheritance
+- **Research Applications**: Use cases in scientific computing
+- **Future Directions**: Planned enhancements
+
+### 5. Check References
+
+All references in `paper.bib` should be accurate and complete. Key reference categories:
+
+- Software engineering best practices (Wilson, Jiménez, Martin, etc.)
+- Existing configuration frameworks (Hydra, OmegaConf, pydantic-settings, etc.)
+- Python Enhancement Proposals (PEP 557, PEP 567, PEP 484, etc.)
+- Design patterns and architecture (Gamma, Fowler, etc.)
+
+### 6. Verify Paper Metadata
+
+Check the YAML frontmatter in `paper.md`:
+
+```yaml
+title: Complete and descriptive title ✅
+tags: Relevant keywords ✅
+authors: Name, ORCID, affiliation ⚠️ (Update ORCID)
+affiliations: Institution details ✅
+date: Submission date ✅
+bibliography: paper.bib ✅
+repository-code: GitHub URL ✅
+url: Documentation URL ✅
+```
+
+## JOSS Submission Process
+
+1. **Pre-submission inquiry** (Optional but recommended):
+   - Open an issue at [https://github.com/openjournals/joss-reviews/issues](https://github.com/openjournals/joss-reviews/issues)
+   - Use the "Pre-submission inquiry" template
+   - Get feedback before formal submission
+
+2. **Formal submission**:
+   - Go to [https://joss.theoj.org/papers/new](https://joss.theoj.org/papers/new)
+   - Provide repository URL: `https://github.com/trissim/objectstate`
+   - The JOSS bot will validate your submission
+   - Fix any issues flagged by the bot
+
+3. **Review process**:
+   - Editor assigns reviewers
+   - Reviewers evaluate software quality, documentation, and paper
+   - Address reviewer comments by updating code/docs/paper
+   - Typical review takes 4-8 weeks
+
+## JOSS Review Checklist
+
+The reviewers will check:
+
+### Software Quality
+- ✅ Installation instructions work
+- ✅ Documentation is comprehensive
+- ✅ Tests are present and pass
+- ✅ Software follows best practices
+- ✅ Examples work as documented
+
+### Paper Quality
+- ✅ Clear summary of software functionality
+- ✅ Statement of need is compelling
+- ✅ Comparison to related work
+- ✅ References are appropriate
+- ✅ Example code works and illustrates key features
+
+### Repository
+- ✅ Open source license
+- ✅ Community guidelines (CONTRIBUTING.md recommended)
+- ✅ Tagged release
+- ✅ DOI (will be generated after acceptance)
+
+## Post-Acceptance
+
+After acceptance, JOSS will:
+
+1. Generate a DOI for your software via Zenodo
+2. Publish the paper with DOI
+3. Create a CrossRef deposit for citations
+4. Add your paper to the JOSS website
+
+## Additional Resources
+
+- JOSS Author Guidelines: [https://joss.readthedocs.io/en/latest/submitting.html](https://joss.readthedocs.io/en/latest/submitting.html)
+- Example papers: Browse [https://joss.theoj.org/papers/published](https://joss.theoj.org/papers/published)
+- Review criteria: [https://joss.readthedocs.io/en/latest/review_criteria.html](https://joss.readthedocs.io/en/latest/review_criteria.html)
+
+## Quick Validation
+
+Before submitting, run these checks:
+
+```bash
+# 1. Ensure paper.md and paper.bib are in the repository root
+ls paper.md paper.bib
+
+# 2. Validate paper with JOSS preview tool (requires Docker)
+docker run --rm -v $(pwd):/data openjournals/paperdraft
+
+# 3. Or use the whedon gem (requires Ruby)
+gem install whedon
+whedon prepare --paper paper.md
+
+# 4. Check that tests pass
+pytest
+
+# 5. Verify documentation builds
+cd docs && make html
+```
+
+## Contact
+
+For questions about the JOSS submission:
+- JOSS discussions: [https://github.com/openjournals/joss/discussions](https://github.com/openjournals/joss/discussions)
+- Email: joss@theoj.org
+
+## Version History
+
+- 2026-01-13: Initial JOSS paper draft created

paper.bib

@@ -0,0 +1,175 @@
+@article{Wilson2014,
+  title={Best practices for scientific computing},
+  author={Wilson, Greg and Aruliah, D A and Brown, C Titus and Hong, Neil P Chue and Davis, Matt and Guy, Richard T and Haddock, Steven HD and Huff, Kathryn D and Mitchell, Ian M and Plumbley, Mark D and others},
+  journal={PLoS biology},
+  volume={12},
+  number={1},
+  pages={e1001745},
+  year={2014},
+  publisher={Public Library of Science San Francisco, USA},
+  doi={10.1371/journal.pbio.1001745}
+}
+
+@article{Jimenez2017,
+  title={Four simple recommendations to encourage best practices in research software},
+  author={Jim{\'e}nez, Rafael C and Kuzak, Mateusz and Alhamdoosh, Monther and Barker, Michelle and Batut, B{\'e}r{\'e}nice and Borg, Mikael and Capella-Gutierrez, Salvador and Hong, Neil Chue and Cook, Martin and Corpas, Manuel and others},
+  journal={F1000Research},
+  volume={6},
+  year={2017},
+  publisher={Faculty of 1000 Ltd},
+  doi={10.12688/f1000research.11407.1}
+}
+
+@book{Martin2008,
+  title={Clean code: a handbook of agile software craftsmanship},
+  author={Martin, Robert C},
+  year={2008},
+  publisher={Pearson Education}
+}
+
+@software{Yadan2019,
+  title={Hydra: A framework for elegantly configuring complex applications},
+  author={Yadan, Omry},
+  year={2019},
+  publisher={GitHub},
+  url={https://github.com/facebookresearch/hydra}
+}
+
+@software{Yadan2021,
+  title={OmegaConf: A hierarchical configuration system for Python},
+  author={Yadan, Omry},
+  year={2021},
+  publisher={GitHub},
+  url={https://github.com/omry/omegaconf}
+}
+
+@software{Colvin2023,
+  title={pydantic-settings: Settings management using Pydantic},
+  author={Colvin, Samuel and others},
+  year={2023},
+  publisher={GitHub},
+  url={https://github.com/pydantic/pydantic-settings}
+}
+
+@software{Google2020,
+  title={ML Collections: A lightweight Python library for storing ML experiment configurations},
+  author={{Google Research}},
+  year={2020},
+  publisher={GitHub},
+  url={https://github.com/google/ml_collections}
+}
+
+@inproceedings{Greff2017,
+  title={Sacred: A tool for facilitating reproducible research},
+  author={Greff, Klaus and Klein, Aaron and Chovanec, Martin and Hutter, Frank and Schmidhuber, J{\"u}rgen},
+  booktitle={ICML 2017 RML Workshop},
+  year={2017}
+}
+
+@book{Gamma1994,
+  title={Design patterns: elements of reusable object-oriented software},
+  author={Gamma, Erich and Helm, Richard and Johnson, Ralph and Vlissides, John},
+  year={1994},
+  publisher={Addison-Wesley}
+}
+
+@book{Fowler2002,
+  title={Patterns of enterprise application architecture},
+  author={Fowler, Martin},
+  year={2002},
+  publisher={Addison-Wesley Professional}
+}
+
+@book{Spinellis2005,
+  title={Code quality: the open source perspective},
+  author={Spinellis, Diomidis},
+  year={2005},
+  publisher={Addison-Wesley Professional}
+}
+
+@inproceedings{Claessen2000,
+  title={Typed logical variables in Haskell},
+  author={Claessen, Koen and Ljungl{\"o}f, Peter},
+  booktitle={Haskell Workshop},
+  year={2000},
+  note={Discussion of lazy evaluation patterns}
+}
+
+@misc{vanRossum2009,
+  title={Python tutorial},
+  author={van Rossum, Guido and Drake, Fred L},
+  year={2009},
+  publisher={Python Software Foundation}
+}
+
+@misc{Smith2018,
+  title={{PEP 557 -- Data Classes}},
+  author={Smith, Eric V},
+  year={2018},
+  howpublished={\url{https://www.python.org/dev/peps/pep-0557/}},
+  note={Python Enhancement Proposal}
+}
+
+@software{Sousa2020,
+  title={python-decouple: Strict separation of settings from code},
+  author={Sousa, Henrique Bastos},
+  year={2020},
+  publisher={GitHub},
+  url={https://github.com/henriquebastos/python-decouple}
+}
+
+@inproceedings{Zaharia2018,
+  title={Accelerating the machine learning lifecycle with {MLflow}},
+  author={Zaharia, Matei and Chen, Andrew and Davidson, Aaron and Ghodsi, Ali and Hong, Sue Ann and Konwinski, Andy and Murching, Siddharth and Nykodym, Tomas and Ogilvie, Paul and Parkhe, Mani and others},
+  booktitle={IEEE Data Engineering Bulletin},
+  volume={41},
+  number={4},
+  pages={39--45},
+  year={2018}
+}
+
+@software{Biewald2020,
+  title={Experiment tracking with {Weights and Biases}},
+  author={Biewald, Lukas},
+  year={2020},
+  url={https://www.wandb.com/}
+}
+
+@software{Facebook2019,
+  title={React Context API},
+  author={{Facebook Inc.}},
+  year={2019},
+  url={https://react.dev/reference/react/createContext},
+  note={Design pattern for passing data through component trees}
+}
+
+@misc{vanRossum1991,
+  title={The {Python} {Language} {Reference}},
+  author={van Rossum, Guido},
+  year={1991},
+  note={Method Resolution Order in Python}
+}
+
+@misc{Selivanov2017,
+  title={{PEP 567 -- Context Variables}},
+  author={Selivanov, Yury and Viehland, Dino},
+  year={2017},
+  howpublished={\url{https://www.python.org/dev/peps/pep-0567/}},
+  note={Python Enhancement Proposal}
+}
+
+@misc{Levkivskyi2016,
+  title={{PEP 526 -- Syntax for Variable Annotations}},
+  author={Levkivskyi, Ivan and Lehtosalo, Jukka and Langa, {\L}ukasz},
+  year={2016},
+  howpublished={\url{https://www.python.org/dev/peps/pep-0526/}},
+  note={Python Enhancement Proposal}
+}
+
+@misc{vanRossum2014,
+  title={{PEP 484 -- Type Hints}},
+  author={van Rossum, Guido and Lehtosalo, Jukka and Langa, {\L}ukasz},
+  year={2014},
+  howpublished={\url{https://www.python.org/dev/peps/pep-0484/}},
+  note={Python Enhancement Proposal}
+}