docs: Add initial community guidelines

Signed-off-by: Ivan Kanakarakis <ivan.kanak@gmail.com>

7 files changed, 422 insertions, 111 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..bcb1de57
--- /dev/null
+++ b/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).
diff --git a/DEVELOPERS.md b/DEVELOPERS.md
new file mode 100644
index 00000000..cdea3cfb
--- /dev/null
+++ b/DEVELOPERS.md
@@ -0,0 +1,12 @@
+# Developing guidelines
+
+## Development Setup
+
+## Running Tests
+
+## Coding Rules
+
+## Commit Message Guidelines
+
+## Writing Documentation
+
diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index c846abff..00000000
--- a/INSTALL
+++ /dev/null
@@ -1,31 +0,0 @@
-You need repoze.who to get the examples working, can be gotten through
-easy_install
-
-    easy_install "repoze.who=1.0.16"
-
-!! 2.0 or newer are missing the form plugin which is used in some instances
-
-Or from the PyPI site if you prefer to do it that way.
-Likewise for pyasn1.
-
-You should get the latest version, which is right now 1.0.18 .
-
-You also need xmlsec, which you can find here:
-
-    http://www.aleksey.com/xmlsec/
-
-On Ubuntu and Debian:
-
-    sudo apt install xmlsec1
-
-You may also need:
-
- mako
- memcached
- python-memcache
-
-Apart from that a normal
-
-    python setup.py install
-
-will install the package.
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 00000000..57172a00
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,106 @@
+## NOTICE
+
+this is not accurate anymore and needs to be reworked.
+
+
+## Release instructions
+
+When releasing a new version, the following steps should be taken:
+
+1. Make sure all automated tests pass.
+
+2. Make sure the package metadata in `setup.py` is up-to-date. You can
+   verify the information by re-generating the egg info:
+
+   ```
+   python setup.py egg_info
+   ```
+
+   and inspecting `src/pysaml2.egg-info/PKG-INFO`. You should also make sure
+   that the long description renders as valid reStructuredText. You can
+   do this by using the `rst2html.py` utility from [docutils]:
+
+   ```
+   python setup.py --long-description | rst2html > test.html
+   ```
+
+   If this will produce warning or errors, PyPI will be unable to render
+   the long description nicely. It will treat it as plain text instead.
+
+3. Update the version in the [VERSION] file and report the changes in
+   [CHANGELOG.md] and commit the changes.:
+
+   ```
+   git add CHANGELOG.md
+   git add VERSION
+   git commit -v -s -m "Release version X.Y.Z"
+   ```
+
+4. Create a release [branch]:
+
+   ```
+   git branch vX.Y.Z
+   ```
+
+5. Create a release [tag]:
+
+   ```
+   git tag -a -s vX.Y.Z -m "Version X.Y.Z"
+   ```
+
+6. Push these changes to Github:
+
+   ```
+   git push --follow-tags origin vX.Y.Z
+   git push --follow-tags origin vX.Y.Z:vX.Y.Z
+   ```
+
+7. Create a source and wheel distribution and upload it to PyPI:
+
+   generate a source and wheel distribution at once
+   ```
+   python setup.py sdist bdist_wheel
+   ```
+
+   generated files are under dist/
+   ```
+   ls dist/
+   ```
+
+   upload release on test.pypi.org
+   ```
+   twine upload --repository-url https://test.pypi.org/legacy/ dist/pysaml2-X.Y.Z*
+   ```
+
+   then, upload release on official pypi.org
+   ```
+   twine upload dist/pysaml2-X.Y.Z*
+   ```
+
+8. Upload the documentation to PyPI. First you need to generate the html
+   version of the documentation:
+
+   ```
+   cd docs/
+   make clean
+   make html
+   cd _build/html
+   zip -r pysaml2-docs.zip *
+   ```
+
+   Submit the generated pysaml2-docs.zip file.
+
+9. Send an email to the pysaml2 list announcing this release
+
+
+**Important:** Once released to PyPI or any other public download location,
+a released egg may *never* be removed, even if it has proven to be a faulty
+release ("brown bag release"). In such a case it should simply be superseded
+immediately by a new, improved release.
+
+
+  [VERSION]: https://github.com/IdentityPython/pysaml2/blob/master/VERSION
+  [CHANGELOG.md]: https://github.com/IdentityPython/pysaml2/blob/master/CHANGELOG.md
+  [docutils]: http://docutils.sourceforge.net/
+  [branch]: https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
+  [tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..bb7c88d8
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,40 @@
+# Security Policy
+
+You can find more information on security incidents
+on the [IdPy security webpage](https://idpy.org/security/).
+
+You read on the [incident response policy](https://github.com/IdentityPython/Governance/blob/master/idpy-incidentresponse.md)
+under the [governance documentation](https://github.com/IdentityPython/Governance).
+
+
+## Incident report / Reporting a Vulnerability
+
+Anyone can submit a potential security vulnerability to `incident-response@idpy.org`.
+The incident-response team will verify the issue and contact you on how this will be
+handled.
+
+
+## Public Discussions
+
+When a new vulnerability is reported and verified, a new security advisory is created on
+GitHub and the issue is assigned a CVE identifier. Progress on the mitigation is tracked
+on a private fork, where the incident-response team and developers communicate to fix
+the issue.
+
+When the fix is ready, a release plan is prepared and all communication channels are
+used to notify the community of the presence of a new issue and the expected release
+plan. This allows the community time to prepare for a security upgrade. (Notice that
+security fixes are not backported at the moment.)
+
+When the advisory is published, GitHub automatically notifies all associated projects of
+the published advisory. Projects that use IdPy projects as dependencies should
+automatically get Pull Requests by dependabot. Additionally, all communication channels
+are used again, to notify the community of the release of a new version of the affected
+software that contains the relevant fixes that mitigate the reported issue.
+
+
+## Supported versions
+
+Notice, that security fixes are not backported at the moment to older releases than the
+latest. The team does not have the capacity to guarantee that these backports will exist.
+You are advised to be prepared to upgrade to the latest version once the fix is out.
diff --git a/docs/FIXUP_COMMITS.md b/docs/FIXUP_COMMITS.md
new file mode 100644
index 00000000..5d7b50a9
--- /dev/null
+++ b/docs/FIXUP_COMMITS.md
@@ -0,0 +1,115 @@
+# Working with fixup commits
+
+This document provides information and guidelines for working with fixup commits:
+- [What are fixup commits](#about-fixup-commits)
+- [Why use fixup commits](#why-fixup-commits)
+- [Creating fixup commits](#create-fixup-commits)
+- [Squashing fixup commits](#squash-fixup-commits)
+
+[This blog post](https://thoughtbot.com/blog/autosquashing-git-commits) is also a good resource on the subject.
+
+
+## <a name="about-fixup-commits"></a> What are fixup commits
+
+At their core, fixup commits are just regular commits with a special commit message:
+The first line of their commit message starts with "fixup! " (notice the space
+after "!") followed by the first line of the commit message of an earlier
+commit (it doesn't have to be the immediately preceding one).
+
+The purpose of a fixup commit is to modify an earlier commit.
+I.e. it allows adding more changes in a new commit, but "marking" them as
+belonging to an earlier commit.
+`Git` provides tools to make it easy to squash fixup commits into the original
+commit at a later time (see [below](#squash-fixup-commits) for details).
+
+For example, let's assume you have added the following commits to your branch:
+
+```
+feat: first commit
+fix: second commit
+```
+
+If you want to add more changes to the first commit, you can create a new
+commit with the commit message: `fixup! feat: first commit`:
+
+```
+feat: first commit
+fix: second commit
+fixup! feat: first commit
+```
+
+
+## <a name="why-fixup-commits"></a> Why use fixup commits
+
+So, when are fixup commits useful?
+
+During the life of a Pull Request, a reviewer might request changes.
+The Pull Request author can make the requested changes and submit them for another review.
+Normally, these changes should be part of one of the original commits of the Pull Request.
+However, amending an existing commit with the changes makes it difficult for
+the reviewer to know exactly what has changed since the last time they reviewed
+the Pull Request.
+
+Here is where fixup commits come in handy.
+By addressing review feedback in fixup commits, you make it very straight
+forward for the reviewer to see what are the new changes that need to be
+reviewed and verify that their earlier feedback has been addressed.
+This can save a lot of effort, especially on larger Pull Requests (where having
+to re-review _all_ the changes is pretty wasteful).
+
+When the time comes to merge the Pull Request into the repository, the merge
+script knows how to automatically squash fixup commits with the corresponding
+regular commits.
+
+
+## <a name="create-fixup-commits"></a> Creating fixup commits
+
+As mentioned [above](#about-fixup-commits), the only thing that differentiates
+a fixup commit from a regular commit is the commit message.
+You can create a fixup commit by specifying an appropriate commit message (i.e.
+`fixup! <original-commit-message-subject>`).
+
+In addition, the `git` command-line tool provides an easy way to create a fixup
+commit via [git commit --fixup](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupltcommitgt):
+
+```sh
+# Create a fixup commit to fix up the last commit on the branch:
+git commit --fixup HEAD ...
+
+# Create a fixup commit to fix up commit with SHA <COMMIT_SHA>:
+git commit --fixup <COMMIT_SHA> ...
+```
+
+
+## <a name="squash-fixup-commits"></a> Squashing fixup commits
+
+As mentioned above, the merge script will automatically squash fixup commits.
+However, sometimes you might want to manually squash a fixup commit.
+
+
+### Rebasing to squash fixup commits
+
+The easiest way to re-order and squash any commit is via [rebasing interactively](https://git-scm.com/docs/git-rebase#_interactive_mode).
+You move a commit right after the one you want to squash it into in the rebase
+TODO list and change the corresponding action from `pick` to `fixup`.
+
+`Git` can do all these automatically for you if you pass the `--autosquash`
+option to `git rebase`. See the [`git` docs](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash)
+for more details.
+
+
+### Additional options
+
+You may like to consider some optional configurations:
+
+
+#### Configuring `git` to auto-squash by default
+
+By default, `git` will not automatically squash fixup commits when
+interactively rebasing. If you prefer to not have to pass the `--autosquash`
+option every time, you can change the default behavior by setting the
+`rebase.autoSquash` `git` config option to true.
+See the [`git` docs](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt-rebaseautoSquash) for more details.
+
+If you have `rebase.autoSquash` set to true, you can pass the `--no-autosquash`
+option to `git rebase` to override and disable this setting.
diff --git a/release-howto.rst b/release-howto.rst
deleted file mode 100644
index 1ea60ba9..00000000
--- a/release-howto.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-Releasing software
--------------------
-
-When releasing a new version, the following steps should be taken:
-
-1. Make sure all automated tests pass.
-
-2. Make sure the package metadata in ``setup.py`` is up-to-date. You can
-   verify the information by re-generating the egg info::
-
-    python setup.py egg_info
-
-   and inspecting ``src/pysaml2.egg-info/PKG-INFO``. You should also make sure
-   that the long description renders as valid reStructuredText. You can
-   do this by using the ``rst2html.py`` utility from docutils_::
-
-    python setup.py --long-description | rst2html > test.html
-
-   If this will produce warning or errors, PyPI will be unable to render
-   the long description nicely. It will treat it as plain text instead.
-
-3. Update the version in the VERSION_ file and report the changes in
-   CHANGELOG.md_ and commit the changes.::
-
-    git add CHANGELOG.md
-    git add VERSION
-    git commit -v -s -m "Release version X.Y.Z"
-
-4. Create a release branch_::
-
-    git branch vX.Y.Z
-
-5. Create a release tag_::
-
-    git tag -a -s vX.Y.Z -m "Version X.Y.Z"
-
-6. Push these changes to Github::
-
-    git push --follow-tags origin vX.Y.Z
-    git push --follow-tags origin vX.Y.Z:vX.Y.Z
-
-7. Create a source and wheel distribution and upload it to PyPI::
-
-    # generate a source and wheel distribution at once
-    python setup.py sdist bdist_wheel
-
-    # generated files are under dist/
-    ls dist/
-
-    # upload release on test.pypi.org
-    twine upload --repository-url https://test.pypi.org/legacy/ dist/pysaml2-X.Y.Z*
-
-    # then, upload release on official pypi.org
-    twine upload dist/pysaml2-X.Y.Z*
-
-8. Upload the documentation to PyPI. First you need to generate the html
-   version of the documentation::
-
-    cd docs/
-    make clean
-    make html
-    cd _build/html
-    zip -r pysaml2-docs.zip *
-
-   Submit the generated pysaml2-docs.zip file.
-
-9. Send an email to the pysaml2 list announcing this release
-
-
-**Important:** Once released to PyPI or any other public download location,
-a released egg may *never* be removed, even if it has proven to be a faulty
-release ("brown bag release"). In such a case it should simply be superseded
-immediately by a new, improved release.
-
-
-.. _VERSION: https://github.com/IdentityPython/pysaml2/blob/master/VERSION
-.. _CHANGELOG.md: https://github.com/IdentityPython/pysaml2/blob/master/CHANGELOG.md
-.. _docutils: http://docutils.sourceforge.net/
-.. _branch: https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
-.. _tag: https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags