Update docs in preparation for release (#1307)

* Update docs in preparation for release * Switch support channel from gitter to telegram
cms-dev · Dec 17, 2024 · 75eaee2 · 75eaee2
1 parent 587c694
commit 75eaee2
Show file tree

Hide file tree

Showing 4 changed files with 117 additions and 79 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,14 +1,28 @@
 # Contributing and pull request process
 
-To contribute, please send an email to [email protected], or ping us on gitter with what you plan to do (unless uncontroversial and/or small), so that we can agree on the best way to implement it.
-
-We appreciate small commits that do one thing, but also that, when possible, each commit doesn't break the master branch. Please use your best judgement for the size of the commit according to these guidelines. If a commit breaks master, we at least require to push together all commits until master is fixed.
-
-We also appreciate a tidy history, so after you write all your code, consider tidying up the commits to reflect what you did at the end, which is usually a simplified version of the process that you followed to reach the final state. Moreover, each commit should not have PEP 8 or pyflakes warnings (see below for how to make sure you don't introduce any).
-
-If your change involves more than one commit, please create a PR for each of them, unless for very small and obvious commits (read: fixing typos, comments, a few obvious lines), or unless some commit breaks master.
-
-During the review, please address all comments by creating one or more 'fixup' commits on top of the branch (no forced push). At the end, either you or one of the owners can squash appropriately the fixups.
+To contribute, please send an email to [email protected], or
+ping us on [Telegram](https://t.me/contestms) with what you plan to do (unless
+uncontroversial and/or small), so that we can agree on the best way to implement
+it.
+
+We appreciate small commits that do one thing, but also that, when possible,
+each commit doesn't break the master branch. Please use your best judgement for
+the size of the commit according to these guidelines. If a commit breaks master,
+we at least require to push together all commits until master is fixed.
+
+We also appreciate a tidy history, so after you write all your code, consider
+tidying up the commits to reflect what you did at the end, which is usually a
+simplified version of the process that you followed to reach the final state.
+Moreover, each commit should not have PEP 8 or pyflakes warnings (see below for
+how to make sure you don't introduce any).
+
+If your change involves more than one commit, please create a PR for each of
+them, unless for very small and obvious commits (read: fixing typos, comments, a
+few obvious lines), or unless some commit breaks master.
+
+During the review, please address all comments by creating one or more 'fixup'
+commits on top of the branch (no forced push). At the end, either you or one of
+the owners can squash appropriately the fixups.
 
 # Code style
 
@@ -17,9 +31,11 @@ For Python code, we generally follow [PEP 8](https://www.python.org/dev/peps/pep
 We get around Python flexible type system in several ways:
 * we try to avoid "magic" (e.g., generating or changing classes on the fly);
 * we are fairly verbose with naming, trying to help the reader with following the types;
-* we follow our type annotation system for method and function docstrings (planning to switch to [PEP 484](https://www.python.org/dev/peps/pep-0484/)); see later for the format.
+* we follow our type annotation system for method and function docstrings
+  (planning to switch to [PEP 484](https://www.python.org/dev/peps/pep-0484/));
+  see later for the format.
 
-We support Python 3 only, requiring at least version 3.8.
+We support Python 3 only, requiring at least version 3.9.
 
 # Docstring type annotation format
 

diff --git a/README.md b/README.md
@@ -4,8 +4,10 @@ Contest Management System
 Homepage: <http://cms-dev.github.io/>
 
 [![Build Status](https://github.com/cms-dev/cms/workflows/ci/badge.svg)](https://github.com/cms-dev/cms/actions)
-[![codecov](https://codecov.io/gh/cms-dev/cms/branch/master/graph/badge.svg)](https://codecov.io/gh/cms-dev/cms)
-[![Join the chat at https://gitter.im/cms-dev/cms](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/cms-dev/cms?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Codecov](https://codecov.io/gh/cms-dev/cms/branch/master/graph/badge.svg)](https://codecov.io/gh/cms-dev/cms)
+[![Get support on Telegram](https://img.shields.io/endpoint?label=Support&style=flat-square&url=https%3A%2F%2Fmogyo.ro%2Fquart-apis%2Ftgmembercount%3Fchat_id%3Dcontestms)](https://t.me/contestms)
+
+[🌍 Help translate CMS in your language!](https://cms-dev.oneskyapp.com/collaboration/project?id=392655)
 
 Introduction
 ------------
@@ -47,25 +49,23 @@ Support
 To learn how to install and use CMS, please read the **documentation**,
 available at <https://cms.readthedocs.org/>.
 
-If you have questions or need help troubleshooting some problem,
-contact us in the **chat** at [gitter](https://gitter.im/cms-dev/cms),
-or write on the **support mailing list**
-<[email protected]>, where no registration is required
-(you can see the archives on
-[Google Groups](https://groups.google.com/forum/#!forum/contestms-support)).
+If you have questions or need help troubleshooting some problem, contact us in
+the **chat** on [Telegram](https://t.me/contestms), or write on the **support
+mailing list** <[email protected]>, where no registration is
+required (you can see the archives on [Google
+Groups](https://groups.google.com/forum/#!forum/contestms-support)).
 
-To help with the troubleshooting, you can upload on some online
-pastebin the relevant **log files**, that you can find in
-/var/local/log/cms/ (if CMS was running installed) or in ./log (if it
-was running from the local copy).
+To help with the troubleshooting, you can upload on some online pastebin the
+relevant **log files**, that you can find in `/var/local/log/cms/` (if CMS was
+running installed) or in ./log (if it was running from the local copy).
 
 If you encountered a bug, please file an
-[issue](https://github.com/cms-dev/cms/issues) on **GitHub** following
-the instructions in the issue template.
+[issue](https://github.com/cms-dev/cms/issues) on **GitHub** following the
+instructions in the issue template.
 
-**Please don't file issues to ask for help**, we are happy to help
-on the mailing list or on gitter, and it is more likely somebody will
-answer your query sooner.
+**Please don't file issues to ask for help**, we are happy to help on the
+mailing list or on Telegram, and it is more likely somebody will answer your
+query sooner.
 
 You can subscribe to <[email protected]> to receive
 **announcements** of new releases and other important news. Register on

diff --git a/docs/Installation.rst b/docs/Installation.rst
@@ -16,15 +16,15 @@ These are our requirements (in particular we highlight those that are not usuall
 
 * `GNU compiler collection <https://gcc.gnu.org/>`_ (in particular the C compiler ``gcc``);
 
-* `Python <http://www.python.org/>`_ >= 3.8;
+* `Python <http://www.python.org/>`_ >= 3.9;
 
 * `libcg <http://libcg.sourceforge.net/>`_;
 
 * `TeX Live <https://www.tug.org/texlive/>`_ (only for printing);
 
 * `a2ps <https://www.gnu.org/software/a2ps/>`_ (only for printing).
 
-You will also require a Linux kernel with support for control groups and namespaces. Support has been in the Linux kernel since 2.6.32. Other distributions, or systems with custom kernels, may not have support enabled. At a minimum, you will need to enable the following Linux kernel options: ``CONFIG_CGROUPS``, ``CONFIG_CGROUP_CPUACCT``, ``CONFIG_MEMCG`` (previously called as ``CONFIG_CGROUP_MEM_RES_CTLR``), ``CONFIG_CPUSETS``, ``CONFIG_PID_NS``, ``CONFIG_IPC_NS``, ``CONFIG_NET_NS``. It is anyway suggested to use Linux kernel version at least 3.8.
+You will also require a Linux kernel with support for `cgroupv2 <https://docs.kernel.org/admin-guide/cgroup-v2.html>`_.
 
 Then you require the compilation and execution environments for the languages you will use in your contest:
 
@@ -34,9 +34,9 @@ Then you require the compilation and execution environments for the languages yo
 
 * `Free Pascal <http://www.freepascal.org/>`_ (for Pascal, with executable ``fpc``);
 
-* `Python <http://www.python.org/>`_ >= 3.8 (for Python, with executable ``python3``; in addition you will need ``zip``);
+* `Python <http://www.python.org/>`_ (for Python, with executable ``python3``; in addition you will need ``zip``);
 
-* `PHP <http://www.php.net>`_ >= 5 (for PHP, with executable ``php``);
+* `PHP <http://www.php.net>`_ (for PHP, with executable ``php``);
 
 * `Glasgow Haskell Compiler <https://www.haskell.org/ghc/>`_ (for Haskell, with executable ``ghc``);
 
@@ -71,7 +71,8 @@ The above commands provide a very essential Pascal environment. Consider install
 Arch Linux
 ----------
 
-On Arch Linux, unofficial AUR packages can be found: `cms <http://aur.archlinux.org/packages/cms>`_ or `cms-git <http://aur.archlinux.org/packages/cms-git>`_. However, if you do not want to use them, the following command will install almost all dependencies (some of them can be found in the AUR):
+On Arch Linux, the following command will install almost all dependencies (some
+of them can be found in the AUR):
 
 .. sourcecode:: bash
 
@@ -136,33 +137,17 @@ Installing CMS and its Python dependencies
 
 There are a number of ways to install CMS and its Python dependencies:
 
-Method 1: Global installation with pip
---------------------------------------
-
-There are good reasons to install CMS and its Python dependencies via pip (Python Package Index) instead of your package manager (e.g. apt-get). For example: two different Linux distro (or two different versions of the same distro) may offer two different versions of ``python-sqlalchemy``. When using pip, you can choose to install a *specific version* of ``sqlalchemy`` that is known to work correctly with CMS.
-
-Assuming you have ``pip`` installed, you can do this:
-
-.. sourcecode:: bash
-
-    export SETUPTOOLS_USE_DISTUTILS="stdlib"
-    sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS pip3 install -r requirements.txt
-    sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS python3 setup.py install
-
-This command installs python dependencies globally. Note that on some distros, like Arch Linux, this might interfere with the system package manager. If you want to perform the installation in your home folder instead, then you can do this instead:
-
-.. sourcecode:: bash
-
-    export SETUPTOOLS_USE_DISTUTILS="stdlib"
-    pip3 install --user -r requirements.txt
-    python3 setup.py install --user
-
-Method 2: Virtual environment
+Method 1: Virtual environment
 -----------------------------
 
-An alternative method to perform the installation is with a `virtual environment <https://virtualenv.pypa.io/en/latest/>`_, which is an isolated Python environment that you can put wherever you like and that can be activated/deactivated at will.
+The recommended method to install CMS is via a `virtual environment
+<https://virtualenv.pypa.io/en/latest/>`_, which is an isolated Python
+environment that you can put wherever you like and that can be
+activated/deactivated at will.
 
-You will need to create a virtual environment somewhere in your filesystem. For example, let's assume that you decided to create it under your home directory (as ``~/cms_venv``):
+You will need to create a virtual environment somewhere in your filesystem. For
+example, let's assume that you decided to create it under your home directory
+(as ``~/cms_venv``):
 
 .. sourcecode:: bash
 
@@ -174,7 +159,10 @@ To activate it:
 
     source ~/cms_venv/bin/activate
 
-After the activation, the ``pip`` command will *always* be available (even if it was not available globally, e.g. because you did not install it). In general, every python command (python, pip) will refer to their corresponding virtual version. So, you can install python dependencies by issuing:
+After the activation, the ``pip`` command will *always* be available (even if it
+was not available globally, e.g. because you did not install it). In general,
+every python command (python, pip) will refer to their corresponding virtual
+version. So, you can install python dependencies by issuing:
 
 .. sourcecode:: bash
 
@@ -184,14 +172,48 @@ After the activation, the ``pip`` command will *always* be available (even if it
 
 .. note::
 
-    Once you finished using CMS, you can deactivate the virtual environment by issuing:
+    Once you finished using CMS, you can deactivate the virtual environment by
+    issuing:
 
     .. sourcecode:: bash
 
         deactivate
 
-Method 3: Using your distribution's system packages 
+Method 2: Using the Docker image
+--------------------------------
+
+See :doc:`here <Docker image>` for more information. This method is the
+recommended way for running tests locally and for local development. It hasn't
+been tested in production yet, so use it at your own risk.
+
+Method 3: Global installation with pip
+--------------------------------------
+
+There are good reasons to install CMS and its Python dependencies via pip
+instead of your package manager (e.g. apt-get). For example: two different Linux
+distro (or two different versions of the same distro) may offer two different
+versions of ``python-sqlalchemy``. When using pip, you can choose to install a
+*specific version* of ``sqlalchemy`` that is known to work correctly with CMS.
+
+Assuming you have ``pip`` installed, you can do this:
+
+.. sourcecode:: bash
+
+    export SETUPTOOLS_USE_DISTUTILS="stdlib"
+    sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS pip3 install -r requirements.txt
+    sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS python3 setup.py install
+
+This command installs python dependencies globally. Note that on some distros, like Arch Linux, this might interfere with the system package manager. If you want to perform the installation in your home folder instead, then you can do this instead:
+
+.. sourcecode:: bash
+
+    export SETUPTOOLS_USE_DISTUTILS="stdlib"
+    pip3 install --user -r requirements.txt
+    python3 setup.py install --user
+
+Method 4: Using your distribution's system packages
 ---------------------------------------------------
+
 You might be able to install compatible versions of the dependencies in `requirements.txt`
 through your distribution's packages; this method is not supported.
 

diff --git a/setup.py b/setup.py
@@ -122,24 +122,25 @@ def run(self):
     author_email="[email protected]",
     url="https://github.com/cms-dev/cms",
     download_url="https://github.com/cms-dev/cms/archive/master.tar.gz",
-    description="A contest management system and grader "
-                "for IOI-like programming competitions",
+    description="A contest management system and grader for IOI-like programming competitions",
     packages=find_packages(),
     package_data=PACKAGE_DATA,
     cmdclass={"build_py": build_py_and_l10n},
-    scripts=["scripts/cmsLogService",
-             "scripts/cmsScoringService",
-             "scripts/cmsEvaluationService",
-             "scripts/cmsWorker",
-             "scripts/cmsResourceService",
-             "scripts/cmsChecker",
-             "scripts/cmsContestWebServer",
-             "scripts/cmsAdminWebServer",
-             "scripts/cmsProxyService",
-             "scripts/cmsPrintingService",
-             "scripts/cmsRankingWebServer",
-             "scripts/cmsInitDB",
-             "scripts/cmsDropDB"],
+    scripts=[
+        "scripts/cmsLogService",
+        "scripts/cmsScoringService",
+        "scripts/cmsEvaluationService",
+        "scripts/cmsWorker",
+        "scripts/cmsResourceService",
+        "scripts/cmsChecker",
+        "scripts/cmsContestWebServer",
+        "scripts/cmsAdminWebServer",
+        "scripts/cmsProxyService",
+        "scripts/cmsPrintingService",
+        "scripts/cmsRankingWebServer",
+        "scripts/cmsInitDB",
+        "scripts/cmsDropDB",
+    ],
     entry_points={
         "console_scripts": [
             "cmsRunFunctionalTests=cmstestsuite.RunFunctionalTests:main",
@@ -205,8 +206,7 @@ def run(self):
         "Development Status :: 5 - Production/Stable",
         "Natural Language :: English",
         "Operating System :: POSIX :: Linux",
-        "Programming Language :: Python :: 3.8",
-        "License :: OSI Approved :: "
-        "GNU Affero General Public License v3",
-    ]
+        "Programming Language :: Python :: 3.9",
+        "License :: OSI Approved :: GNU Affero General Public License v3",
+    ],
 )