-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reorganize and improve documentation #81
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
f28375a
Move developer notes into separate document
rlskoeser 23892ae
Update contributing document
rlskoeser 71c4c82
Move all-contributors to a separate file
rlskoeser 5079204
Reorganize examples and add a readme
rlskoeser bcbe63b
Reword link to contributor doc
rlskoeser File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| { | ||
| "files": [ | ||
| "README.md" | ||
| "CONTRIBUTORS.md" | ||
| ], | ||
| "imageSize": 100, | ||
| "commit": true, | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,23 +1,29 @@ | ||
| # Contributing to Undate - A fuzzy date Python library | ||
|
|
||
| # Contributing to undate - a python library for working with uncertain or partially known dates | ||
|
|
||
| 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). | ||
| 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/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". | ||
| 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/)! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Contributors | ||
|
|
||
| <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --> | ||
| [](#contributors-) | ||
| <!-- ALL-CONTRIBUTORS-BADGE:END --> | ||
|
|
||
| <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> | ||
| <!-- prettier-ignore-start --> | ||
| <!-- markdownlint-disable --> | ||
| <table> | ||
| <tbody> | ||
| <tr> | ||
| <td align="center" valign="top" width="14.28%"><a href="https://github.com/ColeDCrawford"><img src="https://avatars.githubusercontent.com/u/16374762?v=4?s=100" width="100px;" alt="Cole Crawford"/><br /><sub><b>Cole Crawford</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=ColeDCrawford" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3AColeDCrawford" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=ColeDCrawford" title="Tests">⚠️</a></td> | ||
| <td align="center" valign="top" width="14.28%"><a href="http://rlskoeser.github.io"><img src="https://avatars.githubusercontent.com/u/691231?v=4?s=100" width="100px;" alt="Rebecca Sutton Koeser"/><br /><sub><b>Rebecca Sutton Koeser</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=rlskoeser" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Arlskoeser" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=rlskoeser" title="Tests">⚠️</a> <a href="#blog-rlskoeser" title="Blogposts">📝</a> <a href="#example-rlskoeser" title="Examples">💡</a> <a href="https://github.com/dh-tech/undate-python/commits?author=rlskoeser" title="Documentation">📖</a> <a href="#platform-rlskoeser" title="Packaging/porting to new platform">📦</a></td> | ||
| <td align="center" valign="top" width="14.28%"><a href="https://github.com/robcast"><img src="https://avatars.githubusercontent.com/u/1488847?v=4?s=100" width="100px;" alt="Robert Casties"/><br /><sub><b>Robert Casties</b></sub></a><br /><a href="#data-robcast" title="Data">🔣</a></td> | ||
| <td align="center" valign="top" width="14.28%"><a href="https://github.com/jdamerow"><img src="https://avatars.githubusercontent.com/u/8881141?v=4?s=100" width="100px;" alt="Julia Damerow"/><br /><sub><b>Julia Damerow</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=jdamerow" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Ajdamerow" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=jdamerow" title="Tests">⚠️</a> <a href="#eventOrganizing-jdamerow" title="Event Organizing">📋</a></td> | ||
| <td align="center" valign="top" width="14.28%"><a href="https://github.com/maltevogl"><img src="https://avatars.githubusercontent.com/u/20907912?v=4?s=100" width="100px;" alt="Malte Vogl"/><br /><sub><b>Malte Vogl</b></sub></a><br /><a href="https://github.com/dh-tech/undate-python/commits?author=maltevogl" title="Code">💻</a> <a href="https://github.com/dh-tech/undate-python/pulls?q=is%3Apr+reviewed-by%3Amaltevogl" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/dh-tech/undate-python/commits?author=maltevogl" title="Tests">⚠️</a> <a href="https://github.com/dh-tech/undate-python/commits?author=maltevogl" title="Documentation">📖</a></td> | ||
| </tr> | ||
| </tbody> | ||
| <tfoot> | ||
| <tr> | ||
| <td align="center" size="13px" colspan="7"> | ||
| <img src="https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg"> | ||
| <a href="https://all-contributors.js.org/docs/en/bot/usage">Add your contributions</a> | ||
| </img> | ||
| </td> | ||
| </tr> | ||
| </tfoot> | ||
| </table> | ||
|
|
||
| <!-- markdownlint-restore --> | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| <!-- ALL-CONTRIBUTORS-LIST:END --> | ||
| <!-- prettier-ignore-start --> | ||
| <!-- markdownlint-disable --> | ||
|
|
||
| <!-- markdownlint-restore --> | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| <!-- ALL-CONTRIBUTORS-LIST:END --> | ||
|
|
||
| ### 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -57,6 +57,7 @@ dev = | |
| twine | ||
| wheel | ||
| build | ||
| mypy | ||
| %(docs)s | ||
| test = | ||
| pytest>=7.2 | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, these are helpful and comprehensive and should help folks get up and running quickly