From f952b7632703bfd742e07023b0480c33ebe25c0c Mon Sep 17 00:00:00 2001 From: William Di Luigi Date: Mon, 16 Dec 2024 23:20:57 +0100 Subject: [PATCH 1/3] Update docs in preparation for release --- docs/Installation.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/Installation.rst b/docs/Installation.rst index 1bc4ca04bb..bb3113dad7 100644 --- a/docs/Installation.rst +++ b/docs/Installation.rst @@ -16,7 +16,7 @@ These are our requirements (in particular we highlight those that are not usuall * `GNU compiler collection `_ (in particular the C compiler ``gcc``); -* `Python `_ >= 3.8; +* `Python `_ >= 3.9; * `libcg `_; @@ -24,7 +24,7 @@ These are our requirements (in particular we highlight those that are not usuall * `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 `_. 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 `_ (for Pascal, with executable ``fpc``); -* `Python `_ >= 3.8 (for Python, with executable ``python3``; in addition you will need ``zip``); +* `Python `_ (for Python, with executable ``python3``; in addition you will need ``zip``); -* `PHP `_ >= 5 (for PHP, with executable ``php``); +* `PHP `_ (for PHP, with executable ``php``); * `Glasgow Haskell Compiler `_ (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 `_ or `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,7 +137,12 @@ 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 +Method 1: Using the Docker image +-------------------------------- + +See :doc:`here ` for more information. + +Method 2: 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. @@ -157,7 +163,7 @@ This command installs python dependencies globally. Note that on some distros, l pip3 install --user -r requirements.txt python3 setup.py install --user -Method 2: Virtual environment +Method 3: Virtual environment ----------------------------- An alternative method to perform the installation is with a `virtual environment `_, which is an isolated Python environment that you can put wherever you like and that can be activated/deactivated at will. @@ -190,7 +196,7 @@ After the activation, the ``pip`` command will *always* be available (even if it deactivate -Method 3: Using your distribution's system packages +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. From 08039dec9a81f6c4c4494687bbe4b3c692470eda Mon Sep 17 00:00:00 2001 From: William Di Luigi Date: Tue, 17 Dec 2024 00:06:59 +0100 Subject: [PATCH 2/3] Re-order methods --- docs/Installation.rst | 76 ++++++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 30 deletions(-) diff --git a/docs/Installation.rst b/docs/Installation.rst index bb3113dad7..8c6aaecf62 100644 --- a/docs/Installation.rst +++ b/docs/Installation.rst @@ -137,67 +137,83 @@ Installing CMS and its Python dependencies There are a number of ways to install CMS and its Python dependencies: -Method 1: Using the Docker image --------------------------------- +Method 1: Virtual environment +----------------------------- -See :doc:`here ` for more information. +The recommended method to install CMS is via a `virtual environment +`_, which is an isolated Python +environment that you can put wherever you like and that can be +activated/deactivated at will. -Method 2: Global installation with pip --------------------------------------- +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``): -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. +.. sourcecode:: bash -Assuming you have ``pip`` installed, you can do this: + python3 -m venv ~/cms_venv + +To activate it: .. 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 + source ~/cms_venv/bin/activate -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: +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 export SETUPTOOLS_USE_DISTUTILS="stdlib" - pip3 install --user -r requirements.txt - python3 setup.py install --user + pip3 install -r requirements.txt + python3 setup.py install -Method 3: Virtual environment ------------------------------ +.. note:: -An alternative method to perform the installation is with a `virtual environment `_, which is an isolated Python environment that you can put wherever you like and that can be activated/deactivated at will. + Once you finished using CMS, you can deactivate the virtual environment by + issuing: -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 -.. sourcecode:: bash + deactivate - python3 -m venv ~/cms_venv +Method 2: Using the Docker image +-------------------------------- -To activate it: +See :doc:`here ` 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. -.. sourcecode:: bash +Method 3: Global installation with pip +-------------------------------------- - source ~/cms_venv/bin/activate +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. -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: +Assuming you have ``pip`` installed, you can do this: .. sourcecode:: bash export SETUPTOOLS_USE_DISTUTILS="stdlib" - pip3 install -r requirements.txt - python3 setup.py install - -.. note:: + sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS pip3 install -r requirements.txt + sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS python3 setup.py install - Once you finished using CMS, you can deactivate the virtual environment by issuing: +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 +.. sourcecode:: bash - deactivate + 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. From ec82fc2480c08079a1c8c1d78de1e8064adf1ffc Mon Sep 17 00:00:00 2001 From: William Di Luigi Date: Tue, 17 Dec 2024 01:05:18 +0100 Subject: [PATCH 3/3] Switch support channel from gitter to telegram And some formatting fixes made by the IDE --- .github/CONTRIBUTING.md | 38 +++++++++++++++++++++++++++----------- README.md | 34 +++++++++++++++++----------------- setup.py | 38 +++++++++++++++++++------------------- 3 files changed, 63 insertions(+), 47 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 44b638d5ba..5bb409144b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,14 +1,28 @@ # Contributing and pull request process -To contribute, please send an email to contestms-discuss@googlegroups.com, 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 contestms-discuss@googlegroups.com, 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 index 564eb55b63..b385db707a 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,10 @@ Contest Management System Homepage: [![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 . -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** -, 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** , 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 to receive **announcements** of new releases and other important news. Register on diff --git a/setup.py b/setup.py index 2ac6cd7084..200c843de1 100755 --- a/setup.py +++ b/setup.py @@ -122,24 +122,25 @@ def run(self): author_email="contestms@googlegroups.com", 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", + ], )