Skip to content

Commit 75eaee2

Browse files
wil93wil93
authored
Update docs in preparation for release (#1307)
* Update docs in preparation for release * Switch support channel from gitter to telegram
1 parent 587c694 commit 75eaee2

File tree

4 files changed

+117
-79
lines changed

4 files changed

+117
-79
lines changed

‎.github/CONTRIBUTING.md

+27-11
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,28 @@
11
# Contributing and pull request process
22

3-
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.
4-
5-
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.
6-
7-
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).
8-
9-
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.
10-
11-
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.
3+
To contribute, please send an email to contestms-discuss@googlegroups.com, or
4+
ping us on [Telegram](https://t.me/contestms) with what you plan to do (unless
5+
uncontroversial and/or small), so that we can agree on the best way to implement
6+
it.
7+
8+
We appreciate small commits that do one thing, but also that, when possible,
9+
each commit doesn't break the master branch. Please use your best judgement for
10+
the size of the commit according to these guidelines. If a commit breaks master,
11+
we at least require to push together all commits until master is fixed.
12+
13+
We also appreciate a tidy history, so after you write all your code, consider
14+
tidying up the commits to reflect what you did at the end, which is usually a
15+
simplified version of the process that you followed to reach the final state.
16+
Moreover, each commit should not have PEP 8 or pyflakes warnings (see below for
17+
how to make sure you don't introduce any).
18+
19+
If your change involves more than one commit, please create a PR for each of
20+
them, unless for very small and obvious commits (read: fixing typos, comments, a
21+
few obvious lines), or unless some commit breaks master.
22+
23+
During the review, please address all comments by creating one or more 'fixup'
24+
commits on top of the branch (no forced push). At the end, either you or one of
25+
the owners can squash appropriately the fixups.
1226

1327
# Code style
1428

@@ -17,9 +31,11 @@ For Python code, we generally follow [PEP 8](https://www.python.org/dev/peps/pep
1731
We get around Python flexible type system in several ways:
1832
* we try to avoid "magic" (e.g., generating or changing classes on the fly);
1933
* we are fairly verbose with naming, trying to help the reader with following the types;
20-
* 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.
34+
* we follow our type annotation system for method and function docstrings
35+
(planning to switch to [PEP 484](https://www.python.org/dev/peps/pep-0484/));
36+
see later for the format.
2137

22-
We support Python 3 only, requiring at least version 3.8.
38+
We support Python 3 only, requiring at least version 3.9.
2339

2440
# Docstring type annotation format
2541

‎README.md

+17-17
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@ Contest Management System
44
Homepage: <http://cms-dev.github.io/>
55

66
[![Build Status](https://github.com/cms-dev/cms/workflows/ci/badge.svg)](https://github.com/cms-dev/cms/actions)
7-
[![codecov](https://codecov.io/gh/cms-dev/cms/branch/master/graph/badge.svg)](https://codecov.io/gh/cms-dev/cms)
8-
[![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)
7+
[![Codecov](https://codecov.io/gh/cms-dev/cms/branch/master/graph/badge.svg)](https://codecov.io/gh/cms-dev/cms)
8+
[![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)
9+
10+
[🌍 Help translate CMS in your language!](https://cms-dev.oneskyapp.com/collaboration/project?id=392655)
911

1012
Introduction
1113
------------
@@ -47,25 +49,23 @@ Support
4749
To learn how to install and use CMS, please read the **documentation**,
4850
available at <https://cms.readthedocs.org/>.
4951

50-
If you have questions or need help troubleshooting some problem,
51-
contact us in the **chat** at [gitter](https://gitter.im/cms-dev/cms),
52-
or write on the **support mailing list**
53-
<contestms-support@googlegroups.com>, where no registration is required
54-
(you can see the archives on
55-
[Google Groups](https://groups.google.com/forum/#!forum/contestms-support)).
52+
If you have questions or need help troubleshooting some problem, contact us in
53+
the **chat** on [Telegram](https://t.me/contestms), or write on the **support
54+
mailing list** <contestms-support@googlegroups.com>, where no registration is
55+
required (you can see the archives on [Google
56+
Groups](https://groups.google.com/forum/#!forum/contestms-support)).
5657

57-
To help with the troubleshooting, you can upload on some online
58-
pastebin the relevant **log files**, that you can find in
59-
/var/local/log/cms/ (if CMS was running installed) or in ./log (if it
60-
was running from the local copy).
58+
To help with the troubleshooting, you can upload on some online pastebin the
59+
relevant **log files**, that you can find in `/var/local/log/cms/` (if CMS was
60+
running installed) or in ./log (if it was running from the local copy).
6161

6262
If you encountered a bug, please file an
63-
[issue](https://github.com/cms-dev/cms/issues) on **GitHub** following
64-
the instructions in the issue template.
63+
[issue](https://github.com/cms-dev/cms/issues) on **GitHub** following the
64+
instructions in the issue template.
6565

66-
**Please don't file issues to ask for help**, we are happy to help
67-
on the mailing list or on gitter, and it is more likely somebody will
68-
answer your query sooner.
66+
**Please don't file issues to ask for help**, we are happy to help on the
67+
mailing list or on Telegram, and it is more likely somebody will answer your
68+
query sooner.
6969

7070
You can subscribe to <contestms-announce@googlegroups.com> to receive
7171
**announcements** of new releases and other important news. Register on

‎docs/Installation.rst

+54-32
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,15 @@ These are our requirements (in particular we highlight those that are not usuall
1616
1717
* `GNU compiler collection <https://gcc.gnu.org/>`_ (in particular the C compiler ``gcc``);
1818

19-
* `Python <http://www.python.org/>`_ >= 3.8;
19+
* `Python <http://www.python.org/>`_ >= 3.9;
2020

2121
* `libcg <http://libcg.sourceforge.net/>`_;
2222

2323
* `TeX Live <https://www.tug.org/texlive/>`_ (only for printing);
2424

2525
* `a2ps <https://www.gnu.org/software/a2ps/>`_ (only for printing).
2626

27-
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.
27+
You will also require a Linux kernel with support for `cgroupv2 <https://docs.kernel.org/admin-guide/cgroup-v2.html>`_.
2828

2929
Then you require the compilation and execution environments for the languages you will use in your contest:
3030

@@ -34,9 +34,9 @@ Then you require the compilation and execution environments for the languages yo
3434

3535
* `Free Pascal <http://www.freepascal.org/>`_ (for Pascal, with executable ``fpc``);
3636

37-
* `Python <http://www.python.org/>`_ >= 3.8 (for Python, with executable ``python3``; in addition you will need ``zip``);
37+
* `Python <http://www.python.org/>`_ (for Python, with executable ``python3``; in addition you will need ``zip``);
3838

39-
* `PHP <http://www.php.net>`_ >= 5 (for PHP, with executable ``php``);
39+
* `PHP <http://www.php.net>`_ (for PHP, with executable ``php``);
4040

4141
* `Glasgow Haskell Compiler <https://www.haskell.org/ghc/>`_ (for Haskell, with executable ``ghc``);
4242

@@ -71,7 +71,8 @@ The above commands provide a very essential Pascal environment. Consider install
7171
Arch Linux
7272
----------
7373

74-
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):
74+
On Arch Linux, the following command will install almost all dependencies (some
75+
of them can be found in the AUR):
7576

7677
.. sourcecode:: bash
7778

@@ -136,33 +137,17 @@ Installing CMS and its Python dependencies
136137

137138
There are a number of ways to install CMS and its Python dependencies:
138139

139-
Method 1: Global installation with pip
140-
--------------------------------------
141-
142-
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.
143-
144-
Assuming you have ``pip`` installed, you can do this:
145-
146-
.. sourcecode:: bash
147-
148-
export SETUPTOOLS_USE_DISTUTILS="stdlib"
149-
sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS pip3 install -r requirements.txt
150-
sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS python3 setup.py install
151-
152-
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:
153-
154-
.. sourcecode:: bash
155-
156-
export SETUPTOOLS_USE_DISTUTILS="stdlib"
157-
pip3 install --user -r requirements.txt
158-
python3 setup.py install --user
159-
160-
Method 2: Virtual environment
140+
Method 1: Virtual environment
161141
-----------------------------
162142

163-
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.
143+
The recommended method to install CMS is via a `virtual environment
144+
<https://virtualenv.pypa.io/en/latest/>`_, which is an isolated Python
145+
environment that you can put wherever you like and that can be
146+
activated/deactivated at will.
164147

165-
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``):
148+
You will need to create a virtual environment somewhere in your filesystem. For
149+
example, let's assume that you decided to create it under your home directory
150+
(as ``~/cms_venv``):
166151

167152
.. sourcecode:: bash
168153

@@ -174,7 +159,10 @@ To activate it:
174159

175160
source ~/cms_venv/bin/activate
176161

177-
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:
162+
After the activation, the ``pip`` command will *always* be available (even if it
163+
was not available globally, e.g. because you did not install it). In general,
164+
every python command (python, pip) will refer to their corresponding virtual
165+
version. So, you can install python dependencies by issuing:
178166

179167
.. sourcecode:: bash
180168

@@ -184,14 +172,48 @@ After the activation, the ``pip`` command will *always* be available (even if it
184172

185173
.. note::
186174

187-
Once you finished using CMS, you can deactivate the virtual environment by issuing:
175+
Once you finished using CMS, you can deactivate the virtual environment by
176+
issuing:
188177

189178
.. sourcecode:: bash
190179

191180
deactivate
192181

193-
Method 3: Using your distribution's system packages
182+
Method 2: Using the Docker image
183+
--------------------------------
184+
185+
See :doc:`here <Docker image>` for more information. This method is the
186+
recommended way for running tests locally and for local development. It hasn't
187+
been tested in production yet, so use it at your own risk.
188+
189+
Method 3: Global installation with pip
190+
--------------------------------------
191+
192+
There are good reasons to install CMS and its Python dependencies via pip
193+
instead of your package manager (e.g. apt-get). For example: two different Linux
194+
distro (or two different versions of the same distro) may offer two different
195+
versions of ``python-sqlalchemy``. When using pip, you can choose to install a
196+
*specific version* of ``sqlalchemy`` that is known to work correctly with CMS.
197+
198+
Assuming you have ``pip`` installed, you can do this:
199+
200+
.. sourcecode:: bash
201+
202+
export SETUPTOOLS_USE_DISTUTILS="stdlib"
203+
sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS pip3 install -r requirements.txt
204+
sudo --preserve-env=SETUPTOOLS_USE_DISTUTILS python3 setup.py install
205+
206+
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:
207+
208+
.. sourcecode:: bash
209+
210+
export SETUPTOOLS_USE_DISTUTILS="stdlib"
211+
pip3 install --user -r requirements.txt
212+
python3 setup.py install --user
213+
214+
Method 4: Using your distribution's system packages
194215
---------------------------------------------------
216+
195217
You might be able to install compatible versions of the dependencies in `requirements.txt`
196218
through your distribution's packages; this method is not supported.
197219

‎setup.py

+19-19
Original file line numberDiff line numberDiff line change
@@ -122,24 +122,25 @@ def run(self):
122122
author_email="contestms@googlegroups.com",
123123
url="https://github.com/cms-dev/cms",
124124
download_url="https://github.com/cms-dev/cms/archive/master.tar.gz",
125-
description="A contest management system and grader "
126-
"for IOI-like programming competitions",
125+
description="A contest management system and grader for IOI-like programming competitions",
127126
packages=find_packages(),
128127
package_data=PACKAGE_DATA,
129128
cmdclass={"build_py": build_py_and_l10n},
130-
scripts=["scripts/cmsLogService",
131-
"scripts/cmsScoringService",
132-
"scripts/cmsEvaluationService",
133-
"scripts/cmsWorker",
134-
"scripts/cmsResourceService",
135-
"scripts/cmsChecker",
136-
"scripts/cmsContestWebServer",
137-
"scripts/cmsAdminWebServer",
138-
"scripts/cmsProxyService",
139-
"scripts/cmsPrintingService",
140-
"scripts/cmsRankingWebServer",
141-
"scripts/cmsInitDB",
142-
"scripts/cmsDropDB"],
129+
scripts=[
130+
"scripts/cmsLogService",
131+
"scripts/cmsScoringService",
132+
"scripts/cmsEvaluationService",
133+
"scripts/cmsWorker",
134+
"scripts/cmsResourceService",
135+
"scripts/cmsChecker",
136+
"scripts/cmsContestWebServer",
137+
"scripts/cmsAdminWebServer",
138+
"scripts/cmsProxyService",
139+
"scripts/cmsPrintingService",
140+
"scripts/cmsRankingWebServer",
141+
"scripts/cmsInitDB",
142+
"scripts/cmsDropDB",
143+
],
143144
entry_points={
144145
"console_scripts": [
145146
"cmsRunFunctionalTests=cmstestsuite.RunFunctionalTests:main",
@@ -205,8 +206,7 @@ def run(self):
205206
"Development Status :: 5 - Production/Stable",
206207
"Natural Language :: English",
207208
"Operating System :: POSIX :: Linux",
208-
"Programming Language :: Python :: 3.8",
209-
"License :: OSI Approved :: "
210-
"GNU Affero General Public License v3",
211-
]
209+
"Programming Language :: Python :: 3.9",
210+
"License :: OSI Approved :: GNU Affero General Public License v3",
211+
],
212212
)

0 commit comments

Comments
 (0)