Skip to content

Commit 2211288

Browse files
c00kiemon5terc00kiemon5ter
committed
docs: Add initial community guidelines
Signed-off-by: Ivan Kanakarakis <[email protected]>
1 parent e0516cc commit 2211288

File tree

7 files changed

+422
-111
lines changed

7 files changed

+422
-111
lines changed

‎CONTRIBUTING.md

+149
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

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Developing guidelines
2+
3+
## Development Setup
4+
5+
## Running Tests
6+
7+
## Coding Rules
8+
9+
## Commit Message Guidelines
10+
11+
## Writing Documentation
12+

‎INSTALL

-31
This file was deleted.

‎RELEASE.md

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
## NOTICE
2+
3+
this is not accurate anymore and needs to be reworked.
4+
5+
6+
## Release instructions
7+
8+
When releasing a new version, the following steps should be taken:
9+
10+
1. Make sure all automated tests pass.
11+
12+
2. Make sure the package metadata in `setup.py` is up-to-date. You can
13+
verify the information by re-generating the egg info:
14+
15+
```
16+
python setup.py egg_info
17+
```
18+
19+
and inspecting `src/pysaml2.egg-info/PKG-INFO`. You should also make sure
20+
that the long description renders as valid reStructuredText. You can
21+
do this by using the `rst2html.py` utility from [docutils]:
22+
23+
```
24+
python setup.py --long-description | rst2html > test.html
25+
```
26+
27+
If this will produce warning or errors, PyPI will be unable to render
28+
the long description nicely. It will treat it as plain text instead.
29+
30+
3. Update the version in the [VERSION] file and report the changes in
31+
[CHANGELOG.md] and commit the changes.:
32+
33+
```
34+
git add CHANGELOG.md
35+
git add VERSION
36+
git commit -v -s -m "Release version X.Y.Z"
37+
```
38+
39+
4. Create a release [branch]:
40+
41+
```
42+
git branch vX.Y.Z
43+
```
44+
45+
5. Create a release [tag]:
46+
47+
```
48+
git tag -a -s vX.Y.Z -m "Version X.Y.Z"
49+
```
50+
51+
6. Push these changes to Github:
52+
53+
```
54+
git push --follow-tags origin vX.Y.Z
55+
git push --follow-tags origin vX.Y.Z:vX.Y.Z
56+
```
57+
58+
7. Create a source and wheel distribution and upload it to PyPI:
59+
60+
generate a source and wheel distribution at once
61+
```
62+
python setup.py sdist bdist_wheel
63+
```
64+
65+
generated files are under dist/
66+
```
67+
ls dist/
68+
```
69+
70+
upload release on test.pypi.org
71+
```
72+
twine upload --repository-url https://test.pypi.org/legacy/ dist/pysaml2-X.Y.Z*
73+
```
74+
75+
then, upload release on official pypi.org
76+
```
77+
twine upload dist/pysaml2-X.Y.Z*
78+
```
79+
80+
8. Upload the documentation to PyPI. First you need to generate the html
81+
version of the documentation:
82+
83+
```
84+
cd docs/
85+
make clean
86+
make html
87+
cd _build/html
88+
zip -r pysaml2-docs.zip *
89+
```
90+
91+
Submit the generated pysaml2-docs.zip file.
92+
93+
9. Send an email to the pysaml2 list announcing this release
94+
95+
96+
**Important:** Once released to PyPI or any other public download location,
97+
a released egg may *never* be removed, even if it has proven to be a faulty
98+
release ("brown bag release"). In such a case it should simply be superseded
99+
immediately by a new, improved release.
100+
101+
102+
[VERSION]: https://github.com/IdentityPython/pysaml2/blob/master/VERSION
103+
[CHANGELOG.md]: https://github.com/IdentityPython/pysaml2/blob/master/CHANGELOG.md
104+
[docutils]: http://docutils.sourceforge.net/
105+
[branch]: https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
106+
[tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags

‎SECURITY.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Security Policy
2+
3+
You can find more information on security incidents
4+
on the [IdPy security webpage](https://idpy.org/security/).
5+
6+
You read on the [incident response policy](https://github.com/IdentityPython/Governance/blob/master/idpy-incidentresponse.md)
7+
under the [governance documentation](https://github.com/IdentityPython/Governance).
8+
9+
10+
## Incident report / Reporting a Vulnerability
11+
12+
Anyone can submit a potential security vulnerability to `[email protected]`.
13+
The incident-response team will verify the issue and contact you on how this will be
14+
handled.
15+
16+
17+
## Public Discussions
18+
19+
When a new vulnerability is reported and verified, a new security advisory is created on
20+
GitHub and the issue is assigned a CVE identifier. Progress on the mitigation is tracked
21+
on a private fork, where the incident-response team and developers communicate to fix
22+
the issue.
23+
24+
When the fix is ready, a release plan is prepared and all communication channels are
25+
used to notify the community of the presence of a new issue and the expected release
26+
plan. This allows the community time to prepare for a security upgrade. (Notice that
27+
security fixes are not backported at the moment.)
28+
29+
When the advisory is published, GitHub automatically notifies all associated projects of
30+
the published advisory. Projects that use IdPy projects as dependencies should
31+
automatically get Pull Requests by dependabot. Additionally, all communication channels
32+
are used again, to notify the community of the release of a new version of the affected
33+
software that contains the relevant fixes that mitigate the reported issue.
34+
35+
36+
## Supported versions
37+
38+
Notice, that security fixes are not backported at the moment to older releases than the
39+
latest. The team does not have the capacity to guarantee that these backports will exist.
40+
You are advised to be prepared to upgrade to the latest version once the fix is out.

0 commit comments

Comments
 (0)