Merge pull request #57 from inpefess/better-collaboration-guide

Better collaboration guide

CODE_OF_CONDUCT.rst

@@ -0,0 +1,144 @@
+Contributor Covenant Code of Conduct
+====================================
+
+Our Pledge
+----------
+
+We as members, contributors, and leaders pledge to make participation in
+our community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+-  Demonstrating empathy and kindness toward other people
+-  Being respectful of differing opinions, viewpoints, and experiences
+-  Giving and gracefully accepting constructive feedback
+-  Accepting responsibility and apologizing to those affected by our
+   mistakes, and learning from the experience
+-  Focusing on what is best not just for us as individuals, but for the
+   overall community
+
+Examples of unacceptable behavior include:
+
+-  The use of sexualized language or imagery, and sexual attention or
+   advances of any kind
+-  Trolling, insulting or derogatory comments, and personal or political
+   attacks
+-  Public or private harassment
+-  Publishing others’ private information, such as a physical or email
+   address, without their explicit permission
+-  Other conduct which could reasonably be considered inappropriate in a
+   professional setting
+
+Enforcement Responsibilities
+----------------------------
+
+Community leaders are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, and will
+communicate reasons for moderation decisions when appropriate.
+
+Scope
+-----
+
+This Code of Conduct applies within all community spaces, and also
+applies when an individual is officially representing the community in
+public spaces. Examples of representing our community include using an
+official e-mail address, posting via an official social media account,
+or acting as an appointed representative at an online or offline event.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported to the community leaders responsible for enforcement at `the
+following email <mailto:boris@shminke.ml>`__. All complaints will be
+reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security
+of the reporter of any incident.
+
+Enforcement Guidelines
+----------------------
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of
+this Code of Conduct:
+
+1. Correction
+~~~~~~~~~~~~~
+
+**Community Impact**: Use of inappropriate language or other behavior
+deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an explanation
+of why the behavior was inappropriate. A public apology may be
+requested.
+
+2. Warning
+~~~~~~~~~~
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, for a specified period of
+time. This includes avoiding interactions in community spaces as well as
+external channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+3. Temporary Ban
+~~~~~~~~~~~~~~~~
+
+**Community Impact**: A serious violation of community standards,
+including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No
+public or private interaction with the people involved, including
+unsolicited interaction with those enforcing the Code of Conduct, is
+allowed during this period. Violating these terms may lead to a
+permanent ban.
+
+4. Permanent Ban
+~~~~~~~~~~~~~~~~
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of
+individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction
+within the community.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the `Contributor
+Covenant <https://www.contributor-covenant.org>`__, version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by `Mozilla’s code of conduct
+enforcement ladder <https://github.com/mozilla/diversity>`__.
+
+For answers to common questions about this code of conduct, see the FAQ
+at https://www.contributor-covenant.org/faq. Translations are available
+at https://www.contributor-covenant.org/translations.

CONTRIBUTING.rst

@@ -0,0 +1,158 @@
+============
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated! Every
+little bit helps, and credit will always be given.
+
+You can contribute in many ways:
+
+Types of Contributions
+----------------------
+
+Report Bugs
+~~~~~~~~~~~
+
+Report bugs at https://github.com/inpefess/isabelle-client/issues
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in
+  troubleshooting.
+* Detailed steps to reproduce the bug.
+
+Fix Bugs
+~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "bug"
+and "help wanted" is open to whoever wants to implement a fix for it.
+
+Implement Features
+~~~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for features. Anything tagged with
+"enhancement" and "help wanted" is open to whoever wants to implement
+it.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+Python client for Isabelle server could always use more
+documentation, whether as part of the official docs, in docstrings,
+or even on the web in blog posts, articles, and such.
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at
+https://github.com/inpefess/isabelle-client/issues.
+
+If you are proposing a new feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to
+  implement.
+* Remember that this is a volunteer-driven project, and that
+  contributions are welcome :)
+
+Get Started!
+------------
+
+Ready to contribute? Here's how to set up `isabelle-client` for local
+development. Please note this documentation assumes you already have
+`Git
+<https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`__
+installed and ready to go.
+
+1. `Fork <https://github.com/inpefess/isabelle-client/fork>`__ the
+   `isabelle-client` repo on GitHub.
+
+2. Clone your fork locally:
+
+   .. code:: sh
+
+      cd path_for_the_repo
+      git clone git@github.com:YOUR_NAME/isabelle-client.git
+
+3. It's highly recommended to use a virtual environment for your
+   local development (by the standand means of Python or using
+   Anaconda or anything else):
+
+   .. code:: bash
+
+      python -m venv isabelle-client-env
+      source isabelle-client-env/bin/activate
+
+   This should change the shell to look something like:
+
+   .. code:: bash
+
+      (isabelle-client-env) $
+
+4. Now you can install all the things you need for development:
+
+   .. code:: bash
+		   
+      pip install -U pip
+      pip install -U setuptools wheel poetry
+      poetry install
+      # recommended but not necessary
+      pre-commit install
+
+4. Create a branch for local development:
+
+   .. code:: bash
+
+      git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass code
+   quality checks.
+
+   .. code:: bash
+
+      pydocstyle isabelle_client examples
+      flake8 isabelle_client examples
+      pylint isabelle_client examples
+      mypy isabelle_client examples
+
+6. The next step would be to run the test cases. `isabelle-client`
+   uses pytest and all the existing tests are `doctests
+   <https://docs.python.org/3/library/doctest.html>`__.
+
+   .. code:: bash
+
+      pytest
+
+7. If your contribution is a bug fix or new feature, you may want to
+   add a test to the existing test suite. If possible, do it by
+   doctest, not a dedicates test case file.
+
+8. Commit your changes and push your branch to GitHub:
+
+   .. code:: bash
+
+      git add .
+      git commit -m "Your detailed description of your changes."
+      git push origin name-of-your-bugfix-or-feature
+
+9. Submit a pull request through the GitHub website.
+
+
+Pull Request Guidelines
+-----------------------
+
+Before you submit a pull request, check that it meets these
+guidelines:
+
+1. The pull request should include tests.
+
+2. If the pull request adds functionality, the docs should be
+   updated. Put your new functionality into a function with a
+   docstring, and add the feature to the list in README.rst.
+
+3. The pull request should work for Python 3.7, 3.8, 3.9, 3.10 and
+   3.11. Check https://github.com/inpefess/tptp-lark-parser/pulls and
+   make sure that the tests pass for all supported Python versions.

README.rst

@@ -93,31 +93,8 @@ DOI <https://doi.org/10.1007/978-3-030-81097-9_20>`__.
 How to Contribute
 =================
 
-`Pull requests <https://github.com/inpefess/isabelle-client/pulls>`__
-are welcome. To start:
+Please follow `the contribution guide <https://isabelle-client.readthedocs.io/en/latest/contributing.html>`__ while adhering to `the code of conduct <https://isabelle-client.readthedocs.io/en/latest/code-of-conduct.html>`__.
 
-.. code:: sh
-
-   git clone https://github.com/inpefess/isabelle-client
-   cd isabelle-client
-   # activate python virtual environment with Python 3.7+
-   pip install -U pip
-   pip install -U setuptools wheel poetry
-   poetry install
-   # recommended but not necessary
-   pre-commit install
-
-To check the code quality before creating a pull request, one might run
-the script
-`local-build.sh <https://github.com/inpefess/isabelle-client/blob/master/local-build.sh>`__.
-It locally does nearly the same as the CI pipeline after the PR is
-created.
-
-Reporting issues or problems with the software
-==============================================
-
-Questions and bug reports are welcome on `the
-tracker <https://github.com/inpefess/isabelle-client/issues>`__.
 
 .. |PyPI version| image:: https://badge.fury.io/py/isabelle-client.svg
    :target: https://badge.fury.io/py/isabelle-client

doc/source/code-of-conduct.rst

@@ -0,0 +1 @@
+.. include:: ../../CODE_OF_CONDUCT.rst

doc/source/conf.py

@@ -19,7 +19,7 @@
 
 sys.path.insert(0, os.path.abspath("../.."))
 project = "isabelle-client"
-version = "0.3.10"
+version = "0.3.11"
 copyright = "2021-2022, Boris Shminke"
 author = "Boris Shminke"
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.coverage"]

doc/source/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -21,6 +21,8 @@
 
    usage-example
    package-documentation
+   code-of-conduct
+   contributing
 
 Indices and tables
 *******************