Switch to poetry and add community guidelines

.editorconfig

@@ -8,17 +8,8 @@ tab_width = 4
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
-max_line_length = 88
+max_line_length = 120
 
-[*.y{a,}ml]
+[{*.y{a,}ml,*.html,*.xhtml,*.xml,*.xsd}]
 indent_size = 2
 tab_width = 2
-
-[*.html]
-indent_style = tab
-
-[*.js]
-indent_style = tab
-
-[*.css]
-indent_style = tab

.github/issue_template.md

@@ -1,20 +1,22 @@
-<!--- Provide a general summary of the issue in the Title above -->
+<!-- Provide a general summary of the issue in the Title above -->
 
-## Code Version
+### Code Version
 <!-- What version and/or branch of the code are you running? -->
 
-## Expected Behavior
-<!--- Tell us what should happen -->
+### Expected Behavior
+<!-- Tell us what should happen -->
 
-## Current Behavior
-<!--- Tell us what happens instead of the expected behavior -->
+### Current Behavior
+<!-- Tell us what happens instead of the expected behavior -->
 
-## Possible Solution
-<!--- Not obligatory, but suggest a fix/reason for the bug, -->
+### Possible Solution
+<!-- Not obligatory, but suggest a fix/reason for the bug, -->
+
+### Steps to Reproduce
+<!-- Provide a link to a live example -->
+<!-- or, an unambiguous set of steps to reproduce this bug -->
+<!-- Include code to reproduce, if relevant -->
 
-## Steps to Reproduce
-<!--- Provide a link to a live example, or an unambiguous set of steps to -->
-<!--- reproduce this bug. Include code to reproduce, if relevant -->
 1.
 2.
 3.

.github/pull_request_template.md

@@ -1,11 +1,20 @@
-### All Submissions:
+### Description
 
-* [ ] Have you checked to ensure there aren't other open [Pull Requests](../../pulls) for the same update/change?
-* [ ] Have you added an explanation of what problem you are trying to solve with this PR?
-* [ ] Have you added information on what your changes do and why you chose this as your solution?
-* [ ] Have you written new tests for your changes?
-* [ ] Does your submission pass tests?
-* [ ] This project follows PEP8 style guide. Have you run your code against the 'flake8' linter?
+##### The feature or problem addressed by this PR
 
+<!-- an explaination of the issue that is being resolved with this PR -->
+<!-- or, an explaination of the feature that is being added with this PR -->
+<!-- or, link to an issue describing the problem -->
 
 
+##### What your changes do and why you chose this solution
+
+<!-- description of the technical changes that help resolve the issue -->
+
+
+### Checklist
+
+* [ ] Checked that no other issues or pull requests exist for the same issue/change
+* [ ] Added tests covering the new functionality
+* [ ] Updated documentation OR the change is too minor to be documented
+* [ ] Updated CHANGELOG.md OR changes are insignificant

CONTRIBUTING.md

@@ -0,0 +1,149 @@
+# Contributing guidelines
+
+
+## Questions or Problems
+
+Please, do not open issues for general support questions as we want to keep GitHub
+issues for bug reports and feature requests. Instead, we recommend using our [mailing
+list](https://lists.sunet.se/postorius/lists/idpy-discuss.lists.sunet.se/) or asking
+support-related questions on the [Slack workspace](https://identity-python.slack.com/)
+([invitation](https://join.slack.com/t/identity-python/shared_invite/enQtNzEyNjU1NDI1MjUyLTM2MWI5ZGNhMTk1ZThiOTIxNWY2OTY1ODVmMWNjMzUzMTYxNTY5MzE5N2RlYjExZTIyM2MwYjBjZGE4MGVlMTM)).
+
+To save your and our time, we will systematically close all issues that are requests for
+general support and redirect people to the channels above.
+
+
+## Issues and Bugs
+
+If you find a bug in the source code, you can help us by submitting an issue to our
+GitHub Repository. Even better, you can submit a Pull Request with a fix.
+
+
+## Feature Requests
+
+You can request a new feature by submitting an issue to our GitHub Repository. If you
+would like to implement a new feature, please consider the size of the change in order
+to determine the right steps to proceed:
+
+- For a Major Feature, first open an issue and outline your proposal so that it can be
+  discussed. This process allows us to better coordinate our efforts, prevent
+  duplication of work, and help you to craft the change so that it is successfully
+  accepted into the project.
+
+- Small Features can be crafted and directly submitted as a Pull Request.
+
+
+## Improving Documentation
+
+Should you have a suggestion for the documentation, you can open an issue and outline
+the problem or improvement you have - however, creating the doc fix yourself is much
+better!
+
+If you want to help improve the docs, it's a good idea to let others know what you're
+working on to minimize duplication of effort. Create a new issue (or comment on a
+related existing one) to let others know what you're working on.
+
+If you're making a small change (typo, phrasing) don't worry about filing an issue
+first. Fork the repository in-place and make a quick change on the fly.
+
+For large fixes, please build and test the documentation before submitting the PR to be
+sure you haven't accidentally introduced any layout or formatting issues.
+
+
+## Submission Guidelines
+
+
+### Submitting an Issue
+
+Before you submit an issue, please search the issue tracker.
+An issue for your problem might already exist
+and the discussion might inform you of workarounds readily available.
+
+We want to fix all the issues as soon as possible, but before fixing a bug, we need to
+reproduce and confirm it. In order to reproduce bugs, we require that you provide a
+minimal reproduction. Having a minimal reproducible scenario gives us a wealth of
+important information without going back and forth to you with additional questions.
+
+A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem)
+as well as confirm that we are fixing the right problem.
+
+We require a minimal reproduction to save maintainers' time and ultimately be able to
+fix more bugs. Often, developers find coding problems themselves while preparing a
+minimal reproduction. We understand that sometimes it might be hard to extract
+essential bits of code from a larger codebase, but we really need to isolate the problem
+before we can fix it.
+
+Unfortunately, we are not able to investigate / fix bugs without a minimal reproduction,
+so if we don't hear back from you, we are going to close an issue that doesn't have
+enough information to be reproduced.
+
+
+### Submitting a Pull Request (PR)
+
+Before you submit your Pull Request (PR) consider the following guidelines:
+
+1. Search [GitHub](../pulls) for an open or closed PR
+   that relates to your submission. You don't want to duplicate existing efforts.
+
+2. Be sure that an issue describes the problem you're fixing, or documents the design
+   for the feature you'd like to add. Discussing the design upfront helps to ensure that
+   we're ready to accept your work.
+
+3. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the repo.
+
+4. In your forked repository, make your changes in a new git branch:
+
+   ```shell
+   $ git checkout -b my-fix-branch main
+   ```
+
+5. Create your patch, **including appropriate test cases**.
+   Remember to follow the [Coding Rules](#coding-rules).
+
+6. Run the full test suite, as described in the [developer documentation][dev-doc],
+   and ensure that all tests pass.
+
+7. Commit your changes using a descriptive commit message.
+
+   ```shell
+   $ git commit --all
+   ```
+   Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
+
+8. Push your branch to GitHub:
+
+    ```shell
+    $ git push origin my-fix-branch
+    ```
+
+9. In GitHub, create a new pull request.
+
+
+#### Addressing review feedback
+
+If we ask for changes via code reviews then:
+
+1. Make the required updates to the code.
+2. Re-run the test suite to ensure tests are still passing.
+3. Create a fixup commit and push to your GitHub repository. Update your Pull Request:
+
+   ```shell
+   $ git commit --all --fixup HEAD
+   $ git push
+   ```
+
+   For more info on working with fixup commits see [here](docs/FIXUP_COMMITS.md).
+
+That's it! Thank you for your contribution!
+
+
+## Coding Rules
+
+To ensure consistency throughout the source code,
+keep these rules in mind as you are working:
+
+* All features or bug fixes **must be tested** by one or more specs (unit-tests).
+* All public API methods **must be documented**.
+* We follow [Black's style guide](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html),
+  and wrap all code at **120 characters**.
+  Pre-configured tools to automatically lint and format code are available, see [DEVELOPER.md](DEVELOPER.md).

DEVELOPERS.md

@@ -0,0 +1,102 @@
+# Developing guidelines
+
+If you already cloned the repository and you know that you need to deep dive in the code,
+here are some guidelines to set up your environment.
+
+
+## Development environment setup
+
+### Python versions
+
+To manage multiple Python versions on my system, I use [`pyenv`].
+See the `pyenv` documentation on how to install and configure the tool.
+
+Install the supported python versions and enable them for this project:
+
+```shell
+$ for v in 3.6 3.7 3.8 3.9 3.10; do pyenv install "${v}:latest"; done
+$ pyenv versions --bare | xargs pyenv local
+```
+
+
+### Dependencies
+
+This project uses [`poetry`] to manage dependencies and virtual environments.
+See `poetry`'s [installation instructions] on how to install `poetry` on your system.
+
+I have opted to use [`pipx`] to install and manage `poerty` itself.
+I also use `pipx` to manage other python executables that I want readily available on my system.
+
+Once `poetry` is available on your system, install the development dependencies:
+
+```shell
+$ poetry install --with dev,test,coverage,docs --sync
+```
+
+A virtual environment will be created automatically by `poetry`.
+To enter a shell with the virtual environment loaded use the `shell` command:
+
+```shell
+$ poetry shell
+```
+
+Note that `poetry` doesn't need you to load the virtual environment.
+It will automatically load the virtual environment as you interact with the `poetry` commands.
+
+
+## Running Tests
+
+The tests are written with the [`pytest`] test framework.
+To run the tests invoke `pytest` through `poetry`:
+
+```shell
+$ poetry run pytest
+```
+
+However, the above will only run the tests for the latest python version.
+To test all python versions invoke the test runner [`tox`]:
+
+```shell
+$ poetry run tox
+```
+
+This works because different python versions were made available through `pyenv`.
+
+
+## Coding Rules
+
+Coding style is encoded through the configurations of [`black`] and [`isort`].
+To enforce the rules run:
+
+```shell
+$ poetry run black src/ tests/ example/
+$ poetry run isort src/ tests/ example/
+```
+
+Additional rules and suggestions are generated by [`flake8`].
+Check your code with:
+
+```shell
+$ poetry run flake8 src/
+```
+
+
+## Commit Message Guidelines
+
+(TODO)
+
+
+## Writing Documentation
+
+(TODO)
+
+
+  [`poetry`]: https://python-poetry.org/
+  [installation instructions]: https://python-poetry.org/docs/#installation
+  [`pipx`]: https://pypa.github.io/pipx/
+  [`pyenv`]: https://github.com/pyenv/pyenv
+  [`pytest`]: https://docs.pytest.org/
+  [`tox`]: https://tox.wiki/
+  [`black`]: https://black.readthedocs.io/
+  [`isort`]: https://pycqa.github.io/isort/
+  [`flake8`]: https://flake8.pycqa.org/