From 1818381b7f43b1503d4afaba59e027b1c92a5e44 Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Fri, 4 Aug 2023 11:37:56 +0200 Subject: [PATCH] Docs: Reflect plan to accept bug fixes only further edits shall make the instructions more future-proof --- .github/ISSUE_TEMPLATE.md | 36 ++------------------ CONTRIBUTING.rst | 71 --------------------------------------- docs/contribute.rst | 52 +++++++++++++++++++++++----- docs/install.rst | 45 +++++-------------------- 4 files changed, 56 insertions(+), 148 deletions(-) delete mode 100644 CONTRIBUTING.rst diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index aa19d9a6..436e37e8 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,39 +1,9 @@ - -Used Cerberus version / latest commit: … - -- [ ] I have the capacity to improve the docs when my problem is solved. -- [ ] I have the capacity to submit a patch when a bug is identified. - -- [ ] My question does not concern a practical use-case that I can't figure out - to solve. - ----- - -#### Use-case abstract - - - ----- - -#### Bug report / Feature request - - diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 0a12c876..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,71 +0,0 @@ -How to Contribute -================= - -Contributions are welcome! Not familiar with the codebase yet? No problem! -There are many ways to contribute to open source projects: reporting bugs, -helping with the documentation, spreading the word and of course, adding -new features and patches. - -.. note:: - - There's currently a feature freeze until the basic code modernization for - the 2.0 release is finished. Have a look at the ``ROADMAP.md`` for a status - on its progress. - -Getting Started ---------------- -#. Make sure you have a GitHub account. -#. Open a `new issue`_, assuming one does not already exist. -#. Clearly describe the issue including steps to reproduce when it is a bug. - -Making Changes --------------- -* Fork_ the repository on GitHub. -* Create a topic branch from where you want to base your work. -* This is usually the ``1.3.x`` branch. -* Please avoid working directly on this branch, use a new branch created from it. -* Make commits of logical units (if needed rebase your feature branch before - submitting it). -* Make sure your commit messages are in the `proper format`_. -* If your commit fixes an open issue, reference it in the commit message (#15). -* Make sure you have added the necessary tests for your changes. -* Run all the tests to assure nothing else was accidentally broken. -* Install and enable pre-commit_ (``pip install pre-commit``, then ``pre-commit - install``) to ensure styleguides and codechecks are followed. CI will reject - a change that does not conform to the guidelines. -* Don't forget to add yourself to AUTHORS_. - -These guidelines also apply when helping with documentation (actually, for -typos and minor additions you might choose to `fork and edit`_). - -.. _pre-commit: https://pre-commit.com/ - -Submitting Changes ------------------- -* Push your changes to a topic branch in your fork of the repository. -* Submit a `Pull Request`_. -* Wait for maintainer feedback. - -First time contributor? ------------------------ -It's alright. We've all been there. - -Dont' know where to start? --------------------------- -There are usually several TODO comments scattered around the codebase, maybe -check them out and see if you have ideas, or can help with them. Also, check -the `open issues`_ in case there's something that sparks your interest. What -about documentation? I suck at english so if you're fluent with it (or notice -any error), why not help with that? In any case, other than GitHub help_ pages, -you might want to check this excellent `Effective Guide to Pull Requests`_ - -.. _`the repository`: https://github.com/pyeve/cerberus -.. _AUTHORS: https://github.com/pyeve/cerberus/blob/1.3.x/AUTHORS -.. _`open issues`: https://github.com/pyeve/cerberus/issues -.. _`new issue`: https://github.com/pyeve/cerberus/issues/new -.. _Fork: https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo -.. _`proper format`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html -.. _help: https://docs.github.com/ -.. _`Effective Guide to Pull Requests`: https://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/ -.. _`fork and edit`: https://github.blog/2011-04-26-forking-with-the-edit-button/ -.. _`Pull Request`: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request diff --git a/docs/contribute.rst b/docs/contribute.rst index 643a8cb2..bc304c3e 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -1,4 +1,35 @@ -.. include:: ../CONTRIBUTING.rst +How to Contribute +================= + +There are no plans to develop Cerberus further than the current feature set. +Bug fixes and documentation improvements are welcome and will be published with +yearly service releases. + + +Making Changes +-------------- +* Fork_ the repository_ on GitHub. +* Create a new topic branch from the ``1.3.x`` branch. +* Make commits of logical units (if needed rebase your feature branch before + submitting it). +* Make sure your commit messages are in the `proper format`_. +* If your commit fixes an open issue, reference it in the commit message. +* Make sure you have added the necessary tests for your changes. +* Run all the tests to assure nothing else was accidentally broken. +* Install and enable pre-commit_ (``pip install pre-commit``, then ``pre-commit + install``) to ensure styleguides and codechecks are followed. +* Don't forget to add yourself to the ``AUTHORS.rst`` document. + +These guidelines also apply when helping with documentation (actually, for +typos and minor additions you might choose to `fork and edit`_). + + +Submitting Changes +------------------ +* Push your changes to the topic branch in your fork of the repository. +* Submit a `Pull Request`_. +* Wait for maintainer feedback. Please be patient. + Running the Tests ----------------- @@ -10,6 +41,7 @@ with pytest_: $ pytest cerberus/tests + Testing with other Python versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -26,9 +58,9 @@ that the interpreters themselves need to be available on the system. This might take some time the first run as the different virtual environments are created and dependencies are installed. -If something goes **wrong** and one test fails, you might need to run that test -in the specific python version. You can use the created environments to run -some specific tests. For example, if a test suite fails in Python 3.11: +If something goes wrong and one test fails, you might need to run that test in +the specific python version. You can use the created environments to run some +specific tests. For example, if a test suite fails in Python 3.11: .. code-block:: console @@ -36,6 +68,7 @@ some specific tests. For example, if a test suite fails in Python 3.11: Have a look at ``tox.ini`` for the available test environments and their setup. + Running the benchmarks ~~~~~~~~~~~~~~~~~~~~~~ @@ -46,6 +79,7 @@ Cerberus' performance: $ pytest cerberus/benchmarks + Building the HTML-documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -64,10 +98,12 @@ The HTML build is triggered with: The result can be accessed by opening ``docs/_build/html/index.html``. -Source Code ------------ - -Source code is available at `GitHub `_. +.. _Fork: https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo +.. _`fork and edit`: https://github.blog/2011-04-26-forking-with-the-edit-button/ +.. _pre-commit: https://pre-commit.com/ +.. _`proper format`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +.. _`Pull Request`: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request .. _pytest: https://pytest.org +.. _repository: https://github.com/pyeve/cerberus .. _tox: https://tox.readthedocs.io diff --git a/docs/install.rst b/docs/install.rst index 86e5706c..ede44add 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -2,7 +2,10 @@ Cerberus Installation ===================== This part of the documentation covers the installation of Cerberus. The first -step to using any software package is getting it properly installed. +step to using any software package is getting it properly installed. Please +refer to one of the many established ways to work in project-specific virtual +environments, i.e. the `Virtual Environments and Packages`_ section of the +Pyton documentation. Stable Version @@ -18,46 +21,16 @@ Cerberus is on the PyPI_ so all you need to do is: Development Version ------------------- -Cerberus is actively developed in a `GitHub Repository`_ where the code. If you -want to work with the development version, there are two ways: You can either -let ``pip`` pull in the development version, or you can tell it to operate on a -``git`` checkout. Either way, virtualenv is recommended. - -Get the git checkout in a new virtualenv and run in development mode. +Obtain the source (either as source distribution from the PyPI, with ``git`` or +other means that the Github platform provides) and use the following command +in the source's root directory for an editable installation. Subsequent changes +to the source code will affect its following execution without re-installation. .. code-block:: console - $ git clone git@github.com:pyeve/cerberus.git - Initialized empty Git repository in ~/dev/cerberus.git/ - $ cd cerberus - $ virtualenv venv --distribute - New python executable in venv/bin/python - Installing distribute............done. - $ . venv/bin/activate $ pip install -e . - ... - Finished processing dependencies for Cerberus - -This will pull in the dependencies and activate the git head as the current -version inside the virtualenv. Then all you have to do is run ``git pull -origin`` to update to the latest version. - -To just get the development version without git, do this instead: - -.. code-block:: console - - $ mkdir cerberus - $ cd cerberus - $ virtualenv venv --distribute - $ . venv/bin/activate - New python executable in venv/bin/python - Installing distribute............done. - $ pip install git+git://github.com/pyeve/cerberus.git - ... - Cleaning up... - -And you're done! .. _GitHub Repository: https://github.com/pyeve/cerberus .. _PyPI: https://pypi.org/project/Cerberus +.. _Virtual Environments and Packages: https://docs.python.org/3/tutorial/venv.html