Welcome to the RoboCupJunior Soccer rules repository for the 2021 season.
Although the rules have already been made made final and released, we are always on the lookout for changes that may either improve the competition or simplify the rules (or in the best case, both).
Please edit the rules.adoc
file. The easiest way of doing that seems to be following the
GitHub's instructions
on how to edit files in another user's repository.
In the end that should result in a Pull Request.
When suggesting a change, please follow the following rules:
- Small Pull Requests are better than big ones.
- Please only include one 'change type' (i.e. grammar/structure/gameplay ...) in one Pull Request
- Please make sure to fill in the Pull Request template
The rules are written in a human readable formatting langue called AsciiDoc, which should make them quite readable and easy to edit, so please feel free to do so!
We do realize it may look like that. If you do not feel comfortable with suggesting a change using the process above, feel free to create a new thread on the RCJ Soccer forum. Please make sure the title contains the term Rule Change Suggestion and that your submission contains answers to the following sections:
- Describe your suggestion in one or two sentences
- Explain why do you think it should be in the rules
- List the relevant section(s) of previous rules (if applicable)
We can discuss your suggestion there, and if it makes sense someone will
certainly put it into the actual rules.adoc
document.
The rules are written in a format called asciidoc
. It is very similar to
Markdown but unlike Markdown, it is very extensible and has a nice ecosystems
of tools around it. To get a feel for what it looks like, please take a look at
the AsciiDoc Writer's Guide.
Despite how great it is, the rules cannot be built with AsciiDoc alone. They need to be exported into PDF, in a specific format, and we'd also like them to highlight the changes in a nice way and automatically generate IDs for each paragraph. To do all this, the input AsciiDoc file goes thorugh the following steps:
AsciiDoc
->CriticMarked AsciiDoc
(to visualize rule changes in red)CriticMarked AsciiDoc
-> HTMLCriticMarked AsciiDoc
->LaTeX
(for formatting purposes)LaTeX
->LaTeX + RCJ Soccer formatting
(to ensure uniformity of the output)LaTeX + RCJ Soccer formatting
-> PDF
At the end of this process we end up with a HTML and a PDF version of the AsciiDoc file we started with.
This repository is using GitHub Actions which allows us to automatically build the rules whenever any change/update takes place.
If you'd like to try it on your own, it should not be such a big problem, provided you have Docker installed. You can then go thorugh the build process in two easy steps:
docker run -v $(pwd):/documents asciidoctor/docker-asciidoctor .ci/adoc-to-tex.sh rules
docker run -v $(pwd):/documents mrshu/texlive-dblatex .ci/tex-to-pdf.sh rules
Which will make the rules.adoc
file (in the current working directory --
that's the $(pwd)
part) go through the build steps above and generate files
rules.html
and rules.pdf
as a result.
GitHub now has a nice service called Codespaces which allows us to spin up a "development environment" without having to install various dependencies without having to leave the web browser.
Here is a short tutorial on how to edit the rules in Codespaces.
-
First, navigate to the top part of the repository.
-
You should now be able to navigate the
rules.adoc
and/orsuperteam_rules.adoc
files and edit them as you like. -
To actually build rules as a PDF and/or HTML, you can execute the following:
./scripts/build-rules.bash rules
-
After the script has ran, you will see lines such as the following in the output:
See the HTML version at: http://localhost:12345/tmp_rules.html See the PDF version at: http://localhost:12345/tmp_rules.pdf
Clicking on either should bring you to a directory listing, in which you can find tmp_rules.html
and tmp_rules.pdf
and have them load. Note that this is now being served from the Codespaces environment (the actual URL will have the app.github.dev
suffix).