Skip to content

Commit 3007eb7

Browse files
c00kiemon5terc00kiemon5ter
authored
Merge pull request #872 from IdentityPython/feat-poetry
Switch to poetry and add community guidelines
2 parents 15503e1 + 8827ab6 commit 3007eb7

37 files changed

+3361
-926
lines changed

‎.editorconfig

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,8 @@ tab_width = 4
88
end_of_line = lf
99
insert_final_newline = true
1010
trim_trailing_whitespace = true
11-
max_line_length = 88
11+
max_line_length = 120
1212

13-
[*.y{a,}ml]
13+
[{*.y{a,}ml,*.html,*.xhtml,*.xml,*.xsd}]
1414
indent_size = 2
1515
tab_width = 2
16-
17-
[*.html]
18-
indent_style = tab
19-
20-
[*.js]
21-
indent_style = tab
22-
23-
[*.css]
24-
indent_style = tab

‎.github/issue_template.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,22 @@
1-
<!--- Provide a general summary of the issue in the Title above -->
1+
<!-- Provide a general summary of the issue in the Title above -->
22

3-
## Code Version
3+
### Code Version
44
<!-- What version and/or branch of the code are you running? -->
55

6-
## Expected Behavior
7-
<!--- Tell us what should happen -->
6+
### Expected Behavior
7+
<!-- Tell us what should happen -->
88

9-
## Current Behavior
10-
<!--- Tell us what happens instead of the expected behavior -->
9+
### Current Behavior
10+
<!-- Tell us what happens instead of the expected behavior -->
1111

12-
## Possible Solution
13-
<!--- Not obligatory, but suggest a fix/reason for the bug, -->
12+
### Possible Solution
13+
<!-- Not obligatory, but suggest a fix/reason for the bug, -->
14+
15+
### Steps to Reproduce
16+
<!-- Provide a link to a live example -->
17+
<!-- or, an unambiguous set of steps to reproduce this bug -->
18+
<!-- Include code to reproduce, if relevant -->
1419

15-
## Steps to Reproduce
16-
<!--- Provide a link to a live example, or an unambiguous set of steps to -->
17-
<!--- reproduce this bug. Include code to reproduce, if relevant -->
1820
1.
1921
2.
2022
3.

‎.github/pull_request_template.md

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,20 @@
1-
### All Submissions:
1+
### Description
22

3-
* [ ] Have you checked to ensure there aren't other open [Pull Requests](../../pulls) for the same update/change?
4-
* [ ] Have you added an explanation of what problem you are trying to solve with this PR?
5-
* [ ] Have you added information on what your changes do and why you chose this as your solution?
6-
* [ ] Have you written new tests for your changes?
7-
* [ ] Does your submission pass tests?
8-
* [ ] This project follows PEP8 style guide. Have you run your code against the 'flake8' linter?
3+
##### The feature or problem addressed by this PR
94

5+
<!-- an explaination of the issue that is being resolved with this PR -->
6+
<!-- or, an explaination of the feature that is being added with this PR -->
7+
<!-- or, link to an issue describing the problem -->
108

119

10+
##### What your changes do and why you chose this solution
11+
12+
<!-- description of the technical changes that help resolve the issue -->
13+
14+
15+
### Checklist
16+
17+
* [ ] Checked that no other issues or pull requests exist for the same issue/change
18+
* [ ] Added tests covering the new functionality
19+
* [ ] Updated documentation OR the change is too minor to be documented
20+
* [ ] Updated CHANGELOG.md OR changes are insignificant

‎CONTRIBUTING.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Contributing guidelines
2+
3+
4+
## Questions or Problems
5+
6+
Please, do not open issues for general support questions as we want to keep GitHub
7+
issues for bug reports and feature requests. Instead, we recommend using our [mailing
8+
list](https://lists.sunet.se/postorius/lists/idpy-discuss.lists.sunet.se/) or asking
9+
support-related questions on the [Slack workspace](https://identity-python.slack.com/)
10+
([invitation](https://join.slack.com/t/identity-python/shared_invite/enQtNzEyNjU1NDI1MjUyLTM2MWI5ZGNhMTk1ZThiOTIxNWY2OTY1ODVmMWNjMzUzMTYxNTY5MzE5N2RlYjExZTIyM2MwYjBjZGE4MGVlMTM)).
11+
12+
To save your and our time, we will systematically close all issues that are requests for
13+
general support and redirect people to the channels above.
14+
15+
16+
## Issues and Bugs
17+
18+
If you find a bug in the source code, you can help us by submitting an issue to our
19+
GitHub Repository. Even better, you can submit a Pull Request with a fix.
20+
21+
22+
## Feature Requests
23+
24+
You can request a new feature by submitting an issue to our GitHub Repository. If you
25+
would like to implement a new feature, please consider the size of the change in order
26+
to determine the right steps to proceed:
27+
28+
- For a Major Feature, first open an issue and outline your proposal so that it can be
29+
discussed. This process allows us to better coordinate our efforts, prevent
30+
duplication of work, and help you to craft the change so that it is successfully
31+
accepted into the project.
32+
33+
- Small Features can be crafted and directly submitted as a Pull Request.
34+
35+
36+
## Improving Documentation
37+
38+
Should you have a suggestion for the documentation, you can open an issue and outline
39+
the problem or improvement you have - however, creating the doc fix yourself is much
40+
better!
41+
42+
If you want to help improve the docs, it's a good idea to let others know what you're
43+
working on to minimize duplication of effort. Create a new issue (or comment on a
44+
related existing one) to let others know what you're working on.
45+
46+
If you're making a small change (typo, phrasing) don't worry about filing an issue
47+
first. Fork the repository in-place and make a quick change on the fly.
48+
49+
For large fixes, please build and test the documentation before submitting the PR to be
50+
sure you haven't accidentally introduced any layout or formatting issues.
51+
52+
53+
## Submission Guidelines
54+
55+
56+
### Submitting an Issue
57+
58+
Before you submit an issue, please search the issue tracker.
59+
An issue for your problem might already exist
60+
and the discussion might inform you of workarounds readily available.
61+
62+
We want to fix all the issues as soon as possible, but before fixing a bug, we need to
63+
reproduce and confirm it. In order to reproduce bugs, we require that you provide a
64+
minimal reproduction. Having a minimal reproducible scenario gives us a wealth of
65+
important information without going back and forth to you with additional questions.
66+
67+
A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem)
68+
as well as confirm that we are fixing the right problem.
69+
70+
We require a minimal reproduction to save maintainers' time and ultimately be able to
71+
fix more bugs. Often, developers find coding problems themselves while preparing a
72+
minimal reproduction. We understand that sometimes it might be hard to extract
73+
essential bits of code from a larger codebase, but we really need to isolate the problem
74+
before we can fix it.
75+
76+
Unfortunately, we are not able to investigate / fix bugs without a minimal reproduction,
77+
so if we don't hear back from you, we are going to close an issue that doesn't have
78+
enough information to be reproduced.
79+
80+
81+
### Submitting a Pull Request (PR)
82+
83+
Before you submit your Pull Request (PR) consider the following guidelines:
84+
85+
1. Search [GitHub](../pulls) for an open or closed PR
86+
that relates to your submission. You don't want to duplicate existing efforts.
87+
88+
2. Be sure that an issue describes the problem you're fixing, or documents the design
89+
for the feature you'd like to add. Discussing the design upfront helps to ensure that
90+
we're ready to accept your work.
91+
92+
3. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the repo.
93+
94+
4. In your forked repository, make your changes in a new git branch:
95+
96+
```shell
97+
$ git checkout -b my-fix-branch main
98+
```
99+
100+
5. Create your patch, **including appropriate test cases**.
101+
Remember to follow the [Coding Rules](#coding-rules).
102+
103+
6. Run the full test suite, as described in the [developer documentation][dev-doc],
104+
and ensure that all tests pass.
105+
106+
7. Commit your changes using a descriptive commit message.
107+
108+
```shell
109+
$ git commit --all
110+
```
111+
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
112+
113+
8. Push your branch to GitHub:
114+
115+
```shell
116+
$ git push origin my-fix-branch
117+
```
118+
119+
9. In GitHub, create a new pull request.
120+
121+
122+
#### Addressing review feedback
123+
124+
If we ask for changes via code reviews then:
125+
126+
1. Make the required updates to the code.
127+
2. Re-run the test suite to ensure tests are still passing.
128+
3. Create a fixup commit and push to your GitHub repository. Update your Pull Request:
129+
130+
```shell
131+
$ git commit --all --fixup HEAD
132+
$ git push
133+
```
134+
135+
For more info on working with fixup commits see [here](docs/FIXUP_COMMITS.md).
136+
137+
That's it! Thank you for your contribution!
138+
139+
140+
## Coding Rules
141+
142+
To ensure consistency throughout the source code,
143+
keep these rules in mind as you are working:
144+
145+
* All features or bug fixes **must be tested** by one or more specs (unit-tests).
146+
* All public API methods **must be documented**.
147+
* We follow [Black's style guide](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html),
148+
and wrap all code at **120 characters**.
149+
Pre-configured tools to automatically lint and format code are available, see [DEVELOPER.md](DEVELOPER.md).

‎DEVELOPERS.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Developing guidelines
2+
3+
If you already cloned the repository and you know that you need to deep dive in the code,
4+
here are some guidelines to set up your environment.
5+
6+
7+
## Development environment setup
8+
9+
### Python versions
10+
11+
To manage multiple Python versions on my system, I use [`pyenv`].
12+
See the `pyenv` documentation on how to install and configure the tool.
13+
14+
Install the supported python versions and enable them for this project:
15+
16+
```shell
17+
$ for v in 3.6 3.7 3.8 3.9 3.10; do pyenv install "${v}:latest"; done
18+
$ pyenv versions --bare | xargs pyenv local
19+
```
20+
21+
22+
### Dependencies
23+
24+
This project uses [`poetry`] to manage dependencies and virtual environments.
25+
See `poetry`'s [installation instructions] on how to install `poetry` on your system.
26+
27+
I have opted to use [`pipx`] to install and manage `poerty` itself.
28+
I also use `pipx` to manage other python executables that I want readily available on my system.
29+
30+
Once `poetry` is available on your system, install the development dependencies:
31+
32+
```shell
33+
$ poetry install --with dev,test,coverage,docs --sync
34+
```
35+
36+
A virtual environment will be created automatically by `poetry`.
37+
To enter a shell with the virtual environment loaded use the `shell` command:
38+
39+
```shell
40+
$ poetry shell
41+
```
42+
43+
Note that `poetry` doesn't need you to load the virtual environment.
44+
It will automatically load the virtual environment as you interact with the `poetry` commands.
45+
46+
47+
## Running Tests
48+
49+
The tests are written with the [`pytest`] test framework.
50+
To run the tests invoke `pytest` through `poetry`:
51+
52+
```shell
53+
$ poetry run pytest
54+
```
55+
56+
However, the above will only run the tests for the latest python version.
57+
To test all python versions invoke the test runner [`tox`]:
58+
59+
```shell
60+
$ poetry run tox
61+
```
62+
63+
This works because different python versions were made available through `pyenv`.
64+
65+
66+
## Coding Rules
67+
68+
Coding style is encoded through the configurations of [`black`] and [`isort`].
69+
To enforce the rules run:
70+
71+
```shell
72+
$ poetry run black src/ tests/ example/
73+
$ poetry run isort src/ tests/ example/
74+
```
75+
76+
Additional rules and suggestions are generated by [`flake8`].
77+
Check your code with:
78+
79+
```shell
80+
$ poetry run flake8 src/
81+
```
82+
83+
84+
## Commit Message Guidelines
85+
86+
(TODO)
87+
88+
89+
## Writing Documentation
90+
91+
(TODO)
92+
93+
94+
[`poetry`]: https://python-poetry.org/
95+
[installation instructions]: https://python-poetry.org/docs/#installation
96+
[`pipx`]: https://pypa.github.io/pipx/
97+
[`pyenv`]: https://github.com/pyenv/pyenv
98+
[`pytest`]: https://docs.pytest.org/
99+
[`tox`]: https://tox.wiki/
100+
[`black`]: https://black.readthedocs.io/
101+
[`isort`]: https://pycqa.github.io/isort/
102+
[`flake8`]: https://flake8.pycqa.org/

‎INSTALL

Lines changed: 0 additions & 31 deletions
This file was deleted.

‎MANIFEST.in

Lines changed: 0 additions & 18 deletions
This file was deleted.

0 commit comments

Comments
 (0)