mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fixes in rules, guidelines, additional FAQ

Browse Source 
The new FAQ is about how to report bugs in mkiocccentry tools. The rules
and guidelines link to this FAQ.

The rules and guidelines have been corrected and clarified in a number
of ways.
This commit is contained in:
Cody Boone Ferguson committed 2024-07-02 05:24:44 -07:00
1 parent 5b685077ff
commit b9ef640a61
6 files changed
+219 -86
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

next/guidelines.html
+41 -25
View File
@@ -413,7 +413,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
<div id="guidelines_version">
<h2 id="ioccc-guidelines-version">IOCCC Guidelines version</h2>
</div>
<p><strong><code>|</code></strong> These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.3 2024-07-01</strong>.</p>
<p><strong><code>|</code></strong> These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.4 2024-07-02</strong>.</p>
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
<div id="change_marks">
<h3 id="change-marks">Change marks</h3>
@@ -603,28 +603,34 @@ tool will also do a rudimentary check on the <code>Makefile</code> and run other
well. You can override warnings but doing so puts you at risk of violating
<a href="rules.html">rules</a>.</p>
<p><strong><code>|</code></strong> On the other hand, some <strong>issues are an error</strong> and the xz compressed
tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> fails to validate the
<code>.auth.json</code> or <code>.info.json</code> JSON files that <code>mkiocccentry(1)</code> creates, it is an error and
possibly a bug that you should report at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
page</a>.</p>
tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> fails to validate
the <code>.auth.json</code> or <code>.info.json</code> <a href="https://www.json.org/json-en.html">JSON</a> files
that <code>mkiocccentry(1)</code> creates, it is an error and possibly a bug that you
should report at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See the <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting
bugs in the mkiocccentry repo</a>.</p>
<p><strong><code>|</code></strong> Assuming that <code>chkentry(1)</code> passes for both <code>.auth.json</code> and
<code>.info.json</code> then the tarball will be formed and then <code>txzchk(1)</code> will be
executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> should
executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> would
<strong>NOT</strong> form a tarball if there are any issues.</p>
<p><strong><code>|</code></strong> <code>txzchk(1)</code> performs a wide number of sanity checks on the xz
compressed tarball and if any issues (<code>feathers</code> :-) ) are found then it is very
possibly a bug in one of the tools and you should report it at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry
issues page</a>.</p>
compressed tarball and if any issues (<code>feathers</code> :-) ) are found and if you used
<code>mkiocccentry(1)</code>, then it is very possibly a bug in one of the tools and you
should report it at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs
in the mkiocccentry repo</a>.</p>
<p><strong><code>|</code></strong> As part of its sanity checks, <code>txzchk(1)</code> will run <code>fnamchk(1)</code> on the
<em>filename</em> to verify that the name is valid. If this test does not pass, then it
is flagged by <code>txzchk(1)</code> but it is not an error if you wish to ignore it.
Ignoring this, however, risks violating <a href="rules.html#rule17">Rule 17</a> which is a
big risk.</p>
<p><strong><code>|</code></strong> <code>txzchk(1)</code> will show the contents of the tarball which is how the
<code>mkiocccentry(1)</code> shows you the tarball contents for you to review.</p>
big risk. Of course, using <code>mkiocccentry(1)</code> would prevent this from happening.</p>
<p><strong><code>|</code></strong> By default, <code>txzchk(1)</code> will show the contents of the tarball which is
how the <code>mkiocccentry(1)</code> shows you the tarball contents for you to review.</p>
<p><strong><code>|</code></strong> To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has
some options to write <em>OR</em> read from an answers file so you do not have to input
the information again. To write to answers.txt try:</p>
the information again. To write to <code>answers.txt</code> try:</p>
<pre><code> ./mkiocccentry -a answers.txt ...</code></pre>
<p><strong><code>|</code></strong> Alternatively, if you wish to overwrite a file, you can use the <code>-A</code>
flag with the same option argument. Be careful that you do not accidentally
@@ -641,7 +647,7 @@ contents of the tarball and the words:</p>
<p>No feathers stuck in tarball.</p>
</blockquote>
<p><strong><code>|</code></strong> If you give the option <code>-q</code> it will not report anything unless there
are certain error conditions, for instance <code>fnamchk(1)</code> reports there is a
are certain error conditions, for instance if <code>fnamchk(1)</code> reports there is a
problem with the filename; if <code>txzchk(1)</code> exits 0 then there are no problems
detected.</p>
<p><strong><code>|</code></strong> If you wish to run <code>fnamchk(1)</code> directly you can do so like:</p>
@@ -656,20 +662,30 @@ should use <code>chkentry(1)</code>. <code>chkentry(1)</code> accepts more than
If you pass a single argument, it is expected to be a directory that has both
<code>.auth.json</code> and <code>.info.json</code> in it. You can also specify a <code>.auth.json</code> and/or
<code>.info.json</code> file. An argument of <code>.</code> will skip that file. For instance:</p>
<pre><code> ./chkentry test_work # tests entry directory test_work
<pre><code> # test entry directory test_work:
./chkentry test_work
./chkentry .info.json . # run checks on .info.json file
# run checks on .info.json:
./chkentry .info.json .
./chkentry . .auth.json # run checks on .auth.json
# run checks on .auth.json:
./chkentry . .auth.json
./chkentry .info.json .auth.json # run check on both files</code></pre>
<p><strong><code>|</code></strong> If there is a JSON error detected by <code>jparse(8)</code>, then it is an error
and <code>chkentry(1)</code> will report this. If an issue is found in one or both of the
JSON files it will also report this.</p>
<p><strong><code>|</code></strong> At the risk of stating the obvious: you run a very big risk of having
your submission rejected if you package your own tarball and there are any
problems. Even if everything checks out OK you should not expect that everything
<strong>IS</strong> OK.</p>
# run checks on both .info.json and .auth.json:
./chkentry .info.json .auth.json</code></pre>
<p><strong><code>|</code></strong> If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected
by <code>jparse(8)</code>, <strong>then there is a <a href="https://www.json.org/json-en.html">JSON</a>
error and <code>chkentry(1)</code> will report it as an <em>error</em></strong>. If the parsing is OK <strong>but
there <em>is an issue</em> in one or both of the
<a href="https://www.json.org/json-en.html">JSON</a></strong> files <strong>in the context of the IOCCC</strong>,
<em>it will <strong>report this as an error</strong></em>. Thus, if you were to package this manually
then you would be violating <a href="rules.html#rule17">Rule 17</a>.</p>
<p><strong><code>|</code></strong> At the risk of stating the obvious: you run <strong>a very big risk</strong> of having
your submission rejected if you package your own tarball and there are <strong>any
problems</strong>. For instance, if <code>chkentry(1)</code> found a problem in your <code>.info.json</code>
file, the <code>mkiocccentry(1)</code> tool would not package it. But if you were to package
it manually, you would be violating <a href="rules.html#rule17">Rule 17</a>. But even if
everything checks out OK you should not expect that everything <strong>IS</strong> OK.</p>
<p><strong><code>|</code></strong> As you can see, the use of <code>mkiocccentry(1)</code> is <strong>HIGHLY RECOMMENDED</strong>.</p>
<p><strong><code>|</code></strong> We recommend that you use the
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example">example Makefile</a>
next/guidelines.md
+42 -26
View File
@@ -43,7 +43,7 @@ writing by [contacting the judges](../contact.html).
## IOCCC Guidelines version
</div>
**`|`** These [IOCCC guidelines](guidelines.html) are version **28.3 2024-07-01**.
**`|`** These [IOCCC guidelines](guidelines.html) are version **28.4 2024-07-02**.
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -302,33 +302,40 @@ well. You can override warnings but doing so puts you at risk of violating
[rules](rules.html).
**`|`** On the other hand, some **issues are an error** and the xz compressed
tarball **will not be formed**. For instance, if `chkentry(1)` fails to validate the
`.auth.json` or `.info.json` JSON files that `mkiocccentry(1)` creates, it is an error and
possibly a bug that you should report at the [mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues).
tarball **will not be formed**. For instance, if `chkentry(1)` fails to validate
the `.auth.json` or `.info.json` [JSON](https://www.json.org/json-en.html) files
that `mkiocccentry(1)` creates, it is an error and possibly a bug that you
should report at the [mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues). **PLEASE run the
`bug_report.sh` script to help us out here!** See the [the FAQ about reporting
bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
**`|`** Assuming that `chkentry(1)` passes for both `.auth.json` and
`.info.json` then the tarball will be formed and then `txzchk(1)` will be
executed. In this case, there should be no problems as `mkiocccentry(1)` should
executed. In this case, there should be no problems as `mkiocccentry(1)` would
**NOT** form a tarball if there are any issues.
**`|`** `txzchk(1)` performs a wide number of sanity checks on the xz
compressed tarball and if any issues (`feathers` :-) ) are found then it is very
possibly a bug in one of the tools and you should report it at the [mkiocccentry
issues page](https://github.com/ioccc-src/mkiocccentry/issues).
compressed tarball and if any issues (`feathers` :-) ) are found and if you used
`mkiocccentry(1)`, then it is very possibly a bug in one of the tools and you
should report it at the [mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues). **PLEASE run the
`bug_report.sh` script to help us out here!** See [the FAQ about reporting bugs
in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
**`|`** As part of its sanity checks, `txzchk(1)` will run `fnamchk(1)` on the
_filename_ to verify that the name is valid. If this test does not pass, then it
is flagged by `txzchk(1)` but it is not an error if you wish to ignore it.
Ignoring this, however, risks violating [Rule 17](rules.html#rule17) which is a
big risk.
big risk. Of course, using `mkiocccentry(1)` would prevent this from happening.
**`|`** `txzchk(1)` will show the contents of the tarball which is how the
`mkiocccentry(1)` shows you the tarball contents for you to review.
**`|`** By default, `txzchk(1)` will show the contents of the tarball which is
how the `mkiocccentry(1)` shows you the tarball contents for you to review.
**`|`** To help you with editing a submission, the `mkiocccentry(1)` tool has
some options to write _OR_ read from an answers file so you do not have to input
the information again. To write to answers.txt try:
the information again. To write to `answers.txt` try:
``` <!---sh-->
./mkiocccentry -a answers.txt ...
@@ -358,7 +365,7 @@ contents of the tarball and the words:
> No feathers stuck in tarball.
**`|`** If you give the option `-q` it will not report anything unless there
are certain error conditions, for instance `fnamchk(1)` reports there is a
are certain error conditions, for instance if `fnamchk(1)` reports there is a
problem with the filename; if `txzchk(1)` exits 0 then there are no problems
detected.
@@ -381,27 +388,36 @@ If you pass a single argument, it is expected to be a directory that has both
`.info.json` file. An argument of `.` will skip that file. For instance:
``` <!---sh-->
./chkentry test_work # tests entry directory test_work
# test entry directory test_work:
./chkentry test_work
./chkentry .info.json . # run checks on .info.json file
# run checks on .info.json:
./chkentry .info.json .
./chkentry . .auth.json # run checks on .auth.json
# run checks on .auth.json:
./chkentry . .auth.json
./chkentry .info.json .auth.json # run check on both files
# run checks on both .info.json and .auth.json:
./chkentry .info.json .auth.json
```
**`|`** If there is a JSON error detected by `jparse(8)`, then it is an error
and `chkentry(1)` will report this. If an issue is found in one or both of the
JSON files it will also report this.
**`|`** If there is a [JSON](https://www.json.org/json-en.html) issue detected
by `jparse(8)`, **then there is a [JSON](https://www.json.org/json-en.html)
error and `chkentry(1)` will report it as an _error_**. If the parsing is OK **but
there _is an issue_ in one or both of the
[JSON](https://www.json.org/json-en.html)** files **in the context of the IOCCC**,
_it will **report this as an error**_. Thus, if you were to package this manually
then you would be violating [Rule 17](rules.html#rule17).
**`|`** At the risk of stating the obvious: you run a very big risk of having
your submission rejected if you package your own tarball and there are any
problems. Even if everything checks out OK you should not expect that everything
**IS** OK.
**`|`** At the risk of stating the obvious: you run **a very big risk** of having
your submission rejected if you package your own tarball and there are **any
problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
file, the `mkiocccentry(1)` tool would not package it. But if you were to package
it manually, you would be violating [Rule 17](rules.html#rule17). But even if
everything checks out OK you should not expect that everything **IS** OK.
**`|`** As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.
**`|`** We recommend that you use the
[example Makefile](https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example)
from the [IOCCC mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).
next/rules.html
+28 -14
View File
@@ -413,7 +413,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
<div id="rules_version">
<h2 id="ioccc-rules-version">IOCCC Rules version</h2>
</div>
<p><strong><code>|</code></strong> These <a href="rules.html">IOCCC rules</a> are version <strong>28.3 2024-07-01</strong>.</p>
<p><strong><code>|</code></strong> These <a href="rules.html">IOCCC rules</a> are version <strong>28.4 2024-07-02</strong>.</p>
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
<div id="change_marks">
<h3 id="change-marks">Change marks</h3>
@@ -683,13 +683,13 @@ the following files:</p>
<li><code>.info.json</code></li>
<li><code>.auth.json</code></li>
</ul>
<p><strong><code>|</code></strong> The <code>.info.json</code> must be valid JSON and pass the <code>chkentry(1)</code> test.</p>
<p><strong><code>|</code></strong> The <code>.auth.json</code> must be valid JSON and pass the <code>chkentry(1)</code> test.</p>
<p><strong><code>|</code></strong> The <code>.info.json</code> must be valid JSON and pass the <code>chkentry(1)</code> tests.</p>
<p><strong><code>|</code></strong> The <code>.auth.json</code> must be valid JSON and pass the <code>chkentry(1)</code> tests.</p>
<p><strong><code>|</code></strong> You submission may have additional files, however the filenames of those additional files <strong>MUST</strong>:</p>
<ul>
<li>Be less than <strong>100</strong> characters in length</li>
<li>Match the regular expression: <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code></li>
</ul>
<p><strong><code>|</code></strong> * Be less than <strong>100</strong> characters in length<br>
<strong><code>|</code></strong> * Match the regular expression: <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code></p>
<p><strong><code>|</code></strong> The <code>mkiocccentry(1)</code> tool will not package any files that do not meet
those requirements.</p>
<p><strong><code>|</code></strong> The <code>Makefile</code> must be a non-empty file in <a href="https://www.gnu.org/software/make/manual/make.html">GNU
Makefile</a> form. See the
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example">Makefile.example</a>,
@@ -727,20 +727,34 @@ by the <code>mkiocccentry(1)</code> tool):</p>
only be looked at if the submission wins).</li>
<li><code>.info.json</code> which contains information about the entry.</li>
</ul>
<p><strong><code>|</code></strong> The <code>txzchk(1)</code> tool will verify these for you and the <code>chkentry(1)</code>
tool will do additional checks on the contents of the <code>.auth.json</code> and
<code>.info.json</code> files.</p>
<p><strong><code>|</code></strong> The <code>txzchk(1)</code> tool will verify these (and other things) for you and
the <code>chkentry(1)</code> tool will do additional checks on the contents of the
<code>.auth.json</code> and <code>.info.json</code> files.</p>
<p><strong><code>|</code></strong> The tarball filename <strong>MUST</strong> pass <code>fnamchk(1)</code>; the tool <code>txzchk(1)</code>
which is run by <code>mkiocccentry(1)</code> <strong>before packaging your tarball</strong> will run
<code>fnamchk(1)</code>.</p>
will run <code>fnamchk(1)</code> as part of its algorithm. If you use <code>mkiocccentry(1)</code>
there should be no problem but if you were to package things manually it is
possible there could be a problem.</p>
<p><strong><code>|</code></strong> The <code>fnamchk(1)</code>, which <code>txzchk(1)</code> executes, will verify that the
filename is correct.</p>
<p><strong><code>|</code></strong> These checks <strong>MUST PASS</strong>.</p>
<p><strong><code>|</code></strong> Where <a href="#rule17">Rule 17</a> and the tools from the latest
release of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>
conflict, the <a href="../judges.html">IOCCC Judges</a> will use their best judgment which
is likely to favor <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> code.</p>
<p><strong><code>|</code></strong> This means you <strong>MAKE SURE</strong> that you use <code>mkiocccentry(1)</code> to
<p><strong><code>|</code></strong> This means you should <strong>MAKE SURE</strong> that you use <code>mkiocccentry(1)</code> to
package your submission; <code>mkiocccentry(1)</code> will run the above mentioned tools
<strong>before</strong> creating the tarball.</p>
(that do not act on the tarball) <strong>before</strong> creating the tarball and after the
tarball is created it will then verify that the tarball is okay by running
<code>txzchk(1)</code> on it.</p>
<p><strong><code>|</code></strong> These tools will link in the <code>jparse(8)</code> library and <code>chkentry(1)</code>
actually uses the parser to validate the
<a href="https://www.json.org/json-en.html">JSON</a>.</p>
<p><strong><code>|</code></strong> If you run into a problem with one or more of these tools, <strong>PLEASE</strong>
report it at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
page</a>, <strong>making sure to run
<code>bug_report.sh</code></strong>. See the <a href="guidelines.html">guidelines</a> for help here and also
read <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs in the mkiocccentry
repo</a>.</p>
<p><strong><code>|</code></strong> To state the obvious: submissions that violate <a href="#rule17">Rule 17</a> <strong>will be rejected</strong>,
so be sure to use the latest release of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>,
to form and test your submission’s xz compressed tarball.</p>
next/rules.md
+32 -12
View File
@@ -43,7 +43,7 @@ writing by [contacting the judges](../contact.html).
## IOCCC Rules version
</div>
**`|`** These [IOCCC rules](rules.html) are version **28.3 2024-07-01**.
**`|`** These [IOCCC rules](rules.html) are version **28.4 2024-07-02**.
**IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html).
@@ -443,14 +443,17 @@ the following files:
* `.info.json`
* `.auth.json`
**`|`** The `.info.json` must be valid JSON and pass the `chkentry(1)` test.
**`|`** The `.info.json` must be valid JSON and pass the `chkentry(1)` tests.
**`|`** The `.auth.json` must be valid JSON and pass the `chkentry(1)` test.
**`|`** The `.auth.json` must be valid JSON and pass the `chkentry(1)` tests.
**`|`** You submission may have additional files, however the filenames of those additional files **MUST**:
* Be less than **100** characters in length
* Match the regular expression: `^[0-9A-Za-z][0-9A-Za-z._+-]*$`
**`|`** * Be less than **100** characters in length<br>
**`|`** * Match the regular expression: `^[0-9A-Za-z][0-9A-Za-z._+-]*$`
**`|`** The `mkiocccentry(1)` tool will not package any files that do not meet
those requirements.
**`|`** The `Makefile` must be a non-empty file in [GNU
Makefile](https://www.gnu.org/software/make/manual/make.html) form. See the
@@ -496,13 +499,17 @@ by the `mkiocccentry(1)` tool):
only be looked at if the submission wins).
* `.info.json` which contains information about the entry.
**`|`** The `txzchk(1)` tool will verify these for you and the `chkentry(1)`
tool will do additional checks on the contents of the `.auth.json` and
`.info.json` files.
**`|`** The `txzchk(1)` tool will verify these (and other things) for you and
the `chkentry(1)` tool will do additional checks on the contents of the
`.auth.json` and `.info.json` files.
**`|`** The tarball filename **MUST** pass `fnamchk(1)`; the tool `txzchk(1)`
which is run by `mkiocccentry(1)` **before packaging your tarball** will run
`fnamchk(1)`.
will run `fnamchk(1)` as part of its algorithm. If you use `mkiocccentry(1)`
there should be no problem but if you were to package things manually it is
possible there could be a problem.
**`|`** The `fnamchk(1)`, which `txzchk(1)` executes, will verify that the
filename is correct.
**`|`** These checks **MUST PASS**.
@@ -511,9 +518,22 @@ release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
conflict, the [IOCCC Judges](../judges.html) will use their best judgment which
is likely to favor [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) code.
**`|`** This means you **MAKE SURE** that you use `mkiocccentry(1)` to
**`|`** This means you should **MAKE SURE** that you use `mkiocccentry(1)` to
package your submission; `mkiocccentry(1)` will run the above mentioned tools
**before** creating the tarball.
(that do not act on the tarball) **before** creating the tarball and after the
tarball is created it will then verify that the tarball is okay by running
`txzchk(1)` on it.
**`|`** These tools will link in the `jparse(8)` library and `chkentry(1)`
actually uses the parser to validate the
[JSON](https://www.json.org/json-en.html).
**`|`** If you run into a problem with one or more of these tools, **PLEASE**
report it at the [mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues), **making sure to run
`bug_report.sh`**. See the [guidelines](guidelines.html) for help here and also
read [the FAQ about reporting bugs in the mkiocccentry
repo](../faq.html#mkiocccentry_bugs).
**`|`** To state the obvious: submissions that violate [Rule 17](#rule17) **will be rejected**,
so be sure to use the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),