From f28375a9061c25fb40a0b700c4e6d7ec531f925c Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 6 Jun 2024 12:21:17 -0400 Subject: [PATCH 1/5] Move developer notes into separate document --- CONTRIBUTING.md | 2 +- DEVELOPER_NOTES.md | 81 ++++++++++++++++++++++++++++++++++++++++++ README.md | 88 ++-------------------------------------------- setup.cfg | 1 + 4 files changed, 85 insertions(+), 87 deletions(-) create mode 100644 DEVELOPER_NOTES.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bfe5692..e1eb3b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Hey there! If you found your way here that probably means you are curious about how to contribute to this project. This is great! We are always looking for new contributors. If you can't find the information you are looking for in this document or anywhere else in the repo, please consider [opening a ticket](https://github.com/dh-tech/undate-python/issues) so we know there is something we need to address. ## Project Setup -Instructions on how to set up the project locally and how to run the tests can be found [in the Readme file](README.md). +Instructions on how to set up the project locally and how to run the tests can be found in [Developer Notes](DEVELOPER_NOTES.md). ## Submitting Changes If you would like to contribute by submitting bug fixes, improvements, or new features, please fork the repository and then make a pull request to our main branch when you are ready. For details see [this description of the Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). diff --git a/DEVELOPER_NOTES.md b/DEVELOPER_NOTES.md new file mode 100644 index 0000000..ce8fa87 --- /dev/null +++ b/DEVELOPER_NOTES.md @@ -0,0 +1,81 @@ +# Developer instructions + +Ready to contribute to `undate`? Here are some instructions to get you started. + +## Setup + +### Use git to checkout a copy of the repository +```sh +git clone git@github.com:dh-tech/undate-python.git +cd undate-python +``` + +### Install and initialize git flow + +This repository uses [git-flow](https://github.com/nvie/gitflow) branching conventions: +- **main** will always contain the most recent release +- **develop** branch is the latest version of work in progress + +Pull requests for new features should be made against the **develop** branch. + +We recommended installing git-flow. +1. On OSX, use brew or ports, e.g.: `brew install git-flow`; on Ubuntu/Debian, `apt-get install git-flow` +2. Initialize it in your local copy of this repository: run `git flow init` and accept all the defaults. +3. Use `git flow feature start feature-name` to create a new feature development branch. +4. Feature branches can be merged locally with git flow or by GitHub pull request. +4. Use git flow for releases with `git flow release start x.x.x` and `git flow release finish x.x.x`, where x.x.x is the version number for the new release. + +If you cannot or prefer not to install git flow, you can do the equivalent manually. +1. Check out the develop branch: `git checkout develop` +3. Create new feature manually from the develop branch: `git checkout -b feature/xxx-name` + +### Create a Python virtual environment + +Use a recent version of python 3. We highly recommend using a python virtualenv, e.g. +``` +python3 -m venv undate +source undate/bin/activate +``` + +### Install local version of undate with development python dependencies + +Install an editable version of the local package along with python dependencies needed for testing and development. + +```sh +pip install -e ".[dev]" +``` + +## Install pre-commit hooks + +```sh +pre-commit install +``` + +We use [pre-commit](https://pre-commit.com/) for automated checks and consistent formatting. If you're planning to contribute, please install these when you set up your local development. + +## Tests, documentation, and other checks + +## Running unit tests + +Tests can be run with either `tox` or `pytest`. + +To run all the tests in a single test file, use pytest and specify the path to the test: `pytest tests/test_dateformat/test_base.py` + +To test cases by name, use pytest: `pytest -k test_str` + +## Check python types + +Python typing is currently enforced on pull requests as part of a GitHub Actions Continuous Integration check using `mypy`. + +To check types locally: +1. Install the necessary typing libraries (first run only): +```sh +mypy --install-types +``` +2. Run `mypy src/` to check types. + +### Documentation can be built with tox + +```sh +tox -e docs +``` diff --git a/README.md b/README.md index 0000873..6e0ba6f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,4 @@ # undate-python - -[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-) - **undate** is a python library for working with uncertain or partially known dates. @@ -27,93 +24,12 @@ It was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hack Project documentation is available on ReadTheDocs https://undate-python.readthedocs.io/en/latest/ +For instructions on setting up for local development, see [Developer Notes](DEVELOPER_NOTES.md). + ## License This software is licensed under the [Apache 2.0 License](LICENSE.md). -## Installation - -To install the most recent release from PyPI: -```sh -pip install undate -``` - -To install the latest development version from GitHub: -```sh -pip install git+https://github.com/dh-tech/undate-python.git@develop#egg=undate -``` - -To install a specific release or branch, run the following (replace `[tag-name]` with the tag or branch you want to install): -```sh -pip install git+https://github.com/dh-tech/undate-python.git@[tag-name] -``` - -## Instructions to setup for development - -### Clone repo -``` -$ git clone git@github.com:dh-tech/undate-python.git -cd undate-python -``` - -## Setup and initialize git flow - -This repository uses [git-flow](https://github.com/nvie/gitflow) branching conventions: -- **main** will always contain the most recent release -- **develop** branch is the latest version of work in progress - -Pull requests for new features should be made against the **develop** branch. - -It is recommended to install git flow (on OSX, use brew or ports, e.g.: `brew install git-flow`; on Ubuntu/Debian, `apt-get install git-flow`) and then initialize it in this repository via `git flow init` and accept the defaults. Then you can use `git flow feature start` to create feature development branches. - -Alternately, you can check out the develop branch (`git checkout develop`) -and create your branches manually based on develop (`git checkout -b feature/xxx-name`). - -### Set up Python environment -Use a recent version of python 3.x; recommended to use a virtualenv, e.g. -``` -python3 -m venv undate -source undate/bin/activate -``` - -### Install the package - -Install an editable version of the local package along with python dependencies needed for testing and development. - -```sh -pip install -e ".[dev]" -``` - -### Install pre-commit hooks -```sh -pre-commit install -``` - -### Run unit tests -Tests can be run with either `tox` or `pytest`. - -To run all the tests in a single test file, use pytest and specify the path to the test: `pytest tests/test_dateformat/test_base.py` - -To test cases by name, use pytest: `pytest -k test_str` - -### Check python types - -Python typing is currently only enforced by a CI check action using `mypy`. -To run mypy locally, first install mypy and the necessary typing libraries: -```sh -pip install mypy -mypy --install-types -``` - -Once mypy is installed, run `mypy src/` to check. - - -### Create documentation - -```sh -tox -e docs -``` - ## Contributors diff --git a/setup.cfg b/setup.cfg index dc228d6..81bb6f0 100644 --- a/setup.cfg +++ b/setup.cfg @@ -57,6 +57,7 @@ dev = twine wheel build + mypy %(docs)s test = pytest>=7.2 From 23892ae9349a12e81232b95545c304642a1340a9 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 6 Jun 2024 12:27:25 -0400 Subject: [PATCH 2/5] Update contributing document --- CONTRIBUTING.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e1eb3b7..495781e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,4 @@ -# Contributing to Undate - A fuzzy date Python library - +# Contributing to undate - a python library for working with uncertain or partially known dates Hey there! @@ -9,15 +8,22 @@ If you found your way here that probably means you are curious about how to cont Instructions on how to set up the project locally and how to run the tests can be found in [Developer Notes](DEVELOPER_NOTES.md). ## Submitting Changes -If you would like to contribute by submitting bug fixes, improvements, or new features, please fork the repository and then make a pull request to our main branch when you are ready. For details see [this description of the Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). +If you would like to contribute by submitting bug fixes, improvements, or new features, please fork the repository and then make a pull request to undate **develop** branch when you are ready. For details see [this description of the forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). + +Ideally contributions should include documentation and tests for the proposed changes, but if that is a barrier please let us know when you submit a pull request. ## Submitting Bug Reports and Feature Requests If you find a bug or can think a feature you would really like to see being implemented, you can [create a new issue](https://github.com/dh-tech/undate-python/issues). Please first look through the existing issues, however, to avoid duplication of issues. -If you report a bug, please include any error messages you get and a full description of the steps to reproduce the bug. For new feature requests, please clearly describe the functionality you are looking for and, if applicable, why any existing workflow does not suffice. Please also consider, fixing bugs and implementing new features yourself and submit pull request! :) +If you report a bug, please include any error messages you get and a full description of the steps to reproduce the bug. For new feature requests, please clearly describe the functionality you are looking for and, if applicable, why any existing workflow does not suffice. Please also consider fixing bugs and implementing new features yourself and submitting them via pull request! :) + +## Submitting Use Cases and Example Data +We are particularly interested in collecting more use cases and example data where undate would be helpful! + +Example data can be added to the [examples](examples) folder by a pull request. ## Getting Help -The best and recommended way to get help is to join the [DHTech Slack](https://dh-tech.github.io/join/) and ask for help there. Only in cases when this is not feasible at all, you can open a new issue and tag it with "Help Request". +The best and recommended way to get help is to join the [DHTech Slack](https://dh-tech.github.io/join/) and ask for help there. Only in cases when this is not feasible at all, you can open a new issue and tag it with "Help Request". ## DHTech This project started during the DHTech 2022 Hackathon. If you do technical work in the digital humanities and are intersted in meeting like-minded people, [consider joining](https://dh-tech.github.io/join/)! From 71c4c82769d03a5ab75e08c574a020b3c193bf6b Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 6 Jun 2024 12:30:06 -0400 Subject: [PATCH 3/5] Move all-contributors to a separate file --- .all-contributorsrc | 2 +- CONTRIBUTORS.md | 46 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 46 ++------------------------------------------- 3 files changed, 49 insertions(+), 45 deletions(-) create mode 100644 CONTRIBUTORS.md diff --git a/.all-contributorsrc b/.all-contributorsrc index 584146d..aa4224b 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -1,6 +1,6 @@ { "files": [ - "README.md" + "CONTRIBUTORS.md" ], "imageSize": 100, "commit": true, diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 0000000..2077a52 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,46 @@ +# Contributors + + +[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-) + + + + + + + + + + + + + + + + + + + + +
Cole Crawford
Cole Crawford
πŸ’» πŸ‘€ ⚠️		Rebecca Sutton Koeser
Rebecca Sutton Koeser
πŸ’» πŸ‘€ ⚠️ πŸ“ πŸ’‘ πŸ“– πŸ“¦		Robert Casties
Robert Casties
πŸ”£		Julia Damerow
Julia Damerow
πŸ’» πŸ‘€ ⚠️ πŸ“‹		Malte Vogl
Malte Vogl
πŸ’» πŸ‘€ ⚠️ πŸ“–
+ + Add your contributions + +
+ + + + + + + + + + + + + +### Related blog posts + +- [by Rebecca Sutton Koeser](#blog-rlskoeser) + - [Join me for a DHTech hackathon? It’s an un-date!](https://dh-tech.github.io/blog/2023-02-09-hackathon-summary/) 2023-02-09 on DHTech blog diff --git a/README.md b/README.md index 6e0ba6f..d66ca6b 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ It was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hack [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-) +Read [Contributors](CONTRIBUTORS.md) for contribution information. + ## Documentation Project documentation is available on ReadTheDocs https://undate-python.readthedocs.io/en/latest/ @@ -29,47 +31,3 @@ For instructions on setting up for local development, see [Developer Notes](DEVE ## License This software is licensed under the [Apache 2.0 License](LICENSE.md). - -## Contributors - - - - - - - - - - - - - - - - - - - -
Cole Crawford
Cole Crawford
πŸ’» πŸ‘€ ⚠️		Rebecca Sutton Koeser
Rebecca Sutton Koeser
πŸ’» πŸ‘€ ⚠️ πŸ“ πŸ’‘ πŸ“– πŸ“¦		Robert Casties
Robert Casties
πŸ”£		Julia Damerow
Julia Damerow
πŸ’» πŸ‘€ ⚠️ πŸ“‹		Malte Vogl
Malte Vogl
πŸ’» πŸ‘€ ⚠️ πŸ“–
- - Add your contributions - -
- - - - - - - - - - - - - - -### Related blog posts - -- [by Rebecca Sutton Koeser](#blog-rlskoeser) - - [Join me for a DHTech hackathon? It’s an un-date!](https://dh-tech.github.io/blog/2023-02-09-hackathon-summary/) 2023-02-09 on DHTech blog From 507920457df55e172f3cad119836bc7af59f0809 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 6 Jun 2024 12:42:48 -0400 Subject: [PATCH 4/5] Reorganize examples and add a readme --- CONTRIBUTING.md | 2 +- examples/README.md | 7 +++++++ examples/{ => use-cases}/ismi/README.md | 0 .../{ => use-cases}/ismi/data/ismi-om4-date-samples.json | 0 4 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 examples/README.md rename examples/{ => use-cases}/ismi/README.md (100%) rename examples/{ => use-cases}/ismi/data/ismi-om4-date-samples.json (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 495781e..749c3e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ If you report a bug, please include any error messages you get and a full descri ## Submitting Use Cases and Example Data We are particularly interested in collecting more use cases and example data where undate would be helpful! -Example data can be added to the [examples](examples) folder by a pull request. +Example data can be added to the [examples/use-cases](examples/use-cases) folder by a pull request. ## Getting Help The best and recommended way to get help is to join the [DHTech Slack](https://dh-tech.github.io/join/) and ask for help there. Only in cases when this is not feasible at all, you can open a new issue and tag it with "Help Request". diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..bf2a99c --- /dev/null +++ b/examples/README.md @@ -0,0 +1,7 @@ +# undate examples + +Example data and projects with use cases for uncertain date logic and +example code notebooks using undate. + +- [use cases](use-cases) - examples from projects or specific data with use cases for undate +- [notebooks](notebooks) - code notebooks showing how undate can be used on a specific dataset or for a specific problem diff --git a/examples/ismi/README.md b/examples/use-cases/ismi/README.md similarity index 100% rename from examples/ismi/README.md rename to examples/use-cases/ismi/README.md diff --git a/examples/ismi/data/ismi-om4-date-samples.json b/examples/use-cases/ismi/data/ismi-om4-date-samples.json similarity index 100% rename from examples/ismi/data/ismi-om4-date-samples.json rename to examples/use-cases/ismi/data/ismi-om4-date-samples.json From bcbe63bbe1baaf3430647b59be2f8123b67a5be2 Mon Sep 17 00:00:00 2001 From: rlskoeser Date: Thu, 6 Jun 2024 13:18:34 -0400 Subject: [PATCH 5/5] Reword link to contributor doc --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d66ca6b..dff6a50 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ It was initially created as part of a [DH-Tech](https://dh-tech.github.io/) hack [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-) -Read [Contributors](CONTRIBUTORS.md) for contribution information. +Read [Contributors](CONTRIBUTORS.md) for detailed contribution information. ## Documentation