help/content/files/_index.md

---
date: 2019-04-04T15:59:52+02:00
title: Arborescence et fichiers
weight: 10
---

Afin de pouvoir être importé automatiquement sur la plate-forme, vos scénarios
doivent respecter une certaine arborescence que voici :

<pre>
    .
    ├── AUTHORS.txt
    ├── overview.txt
    ├── title.txt
    ├── heading.jpg
    ├── CHID-Titre du défi/
    │   ├── challenge.txt
    │   ├── finished.txt    (opt.)
    │   ├── links.txt
    │   ├── overview.txt
    │   ├── resolution.mp4
    │   ├── statement.txt
    │   ├── hints/          (opt.)
    │   │   ├── DIGESTS.txt
    │   │   └── ...
    │   ├── files/
    │   │   ├── DIGESTS.txt
    │   │   └── ...
    │   └── ressources/
    │       └── ...
    │
    ├── CHID-Titre du défi/
    │   └── ...
    └── ...
</pre>

N'ajoutez pas inutilement de dossiers ou fichiers vides. Ceux-ci doivent sans
doute être optionnels.


### `CHID`

Dans les noms de dossiers, `CHID` correspond à un identifiant permettant de référencer votre défi (pour déclarer une dépendance sur celui-ci par exemple).
L'import s'effectuant selon l'ordre alphabétique, vous devriez utiliser le numéro d'ordre de l'exercice comme identifiant :

<pre>
    .
    ├── 1-Titre du premier défi/
    │   └── ...
    ├── 2-Titre du deuxième défi/
    │   └── ...
    └── ...

</pre>

Dans cet exemple, si l'ordre était déterminé uniquement par l'ordre alphabétique des noms de dossiers, le **d**euxième serait devant le **p**remier (`d<p`).
Ajouter le numéro d'ordre permet de contrôler plus facilement l'ordre des exercices, sans que cela soit affiché dans l'interface.


## Fichiers pour un scénario

### `AUTHORS.txt`

Voir la [page dédiée]({{<relref "authors">}}).


### `title.txt`

Ce fichier peut être utilisé pour y inscrire le nom du scénario, tel qu'il doit apparaître sur l'interface.

Par défaut, sans ce fichier, c'est le nom du dossier contenant les challenges qui est utilisé.


### `heading.jpg`

Chaque scénario devrait avoir une image/photo représentative. Je vous invite
donc à trouver votre bonheur sur : [Unsplash](https://unsplash.com/) ou à
partager un travail personnel. Mais attention aux licences et contraintes
(notamment l'obligation de citer la source ou le photographe) si vous utilisez
un autre service qu'unsplash.

La taille et l'orientation de l'image n'a pas d'importance, mais gardez en tête
que c'est son centre qui sera affiché, si la hauteur dépasse la taille prévue.

![Rendu heading.jpg](scenario_heading.png)


### `overview.txt`

Une présentation rapide du scenario (~2-3 phrases d'accroche pour lecture
rapide), compréhensible par un décideur, petit schéma à l'appui.

Le fichier **doit** comporter une phrase d'accroche (qui sera affichée plus
grosse que les suivantes). Celle-ci correspond à la première ligne de votre
fichier.

Comme l'ensemble des textes importés, vous pouvez utiliser du
[Markdown](https://daringfireball.net/projects/markdown/) pour mettre en forme
vos textes.

Vous pouvez insérer des images dans tous les textes :

    ![alt](path title)

Le chemin *doit* être un chemin _absolu_ vers l'image, considérant la racine
comme étant le dossier du scémario (pour l'overview du thème) ou de l'exercice
(pour les autres textes).

![Rendu overview.txt](scenario_overview_public.png)

![Rendu overview.txt](scenario_headline.png)


## Fichiers pour un défi

### `challenge.txt`

Voir la [page dédiée]({{<relref "challenge">}}).


### `finished.txt`

Remplissez ce fichier optionnel, lorsque vous souhaitez apporter une
information aux participants une fois qu'ils ont validé votre défi.

Comme l'ensemble des textes importés, vous pouvez utiliser du
[Markdown](https://daringfireball.net/projects/markdown/) pour mettre en forme
vos textes.

![Rendu finished.txt](exercice_finished.png)


### `links.txt`

Voir la [page dédiée]({{<relref "links">}}).


### `overview.txt`

Une présentation rapide du défi (~1-2 phrases), compréhensible par un décideur,
petit schéma à l'appui si besoin.

Le fichier **doit** comporter une phrase d'accroche (qui sera affichée plus
grosse que les suivantes). Celle-ci correspond à la première ligne de votre
fichier.

Comme l'ensemble des textes importés, vous pouvez utiliser du
[Markdown](https://daringfireball.net/projects/markdown/) pour mettre en forme
vos textes.

Gardez en tête que les *overview*, que ce soit scénario ou exercices, sont
affichées au public : il s'agit à la fois d'aguicher le participant pour qu'il
fasse votre scénario plutôt que celui d'un autre groupe, mais aussi de donner
envie au public de lire plus en détail.

![Rendu overview.txt](exercice_overview_public.png)

![Rendu overview.txt](exercice_headline.png)


### `resolution.mp4`

Voir la [page dédiée]({{<relref "resolution">}}).


### `statement.txt`

contenant le scénario du challenge, tel qu'il sera affiché sur le site, à destination des participants
Une présentation rapide du défi (~1-2 phrases), compréhensible par un décideur,
petit schéma à l'appui si besoin.

Le fichier **doit** comporter une phrase d'accroche (qui sera affichée plus
grosse que les suivantes). Celle-ci correspond à la première ligne de votre
fichier.

Comme l'ensemble des textes importés, vous pouvez utiliser du
[Markdown](https://daringfireball.net/projects/markdown/) pour mettre en forme
vos textes.

![Rendu statement.txt](exercice_statement.png)


### `files/`

Utilisez ce dossier pour y placer les fichiers que vous mettez à disposition
des participants.

Chaque fichier doit avoir une entrée correspondante dans le fichier
`DIGESTS.txt` ; plus d'infos sur la page [`DIGESTS.txt`]({{<relref
"digests">}}).

- Pas plus  4GB à télécharger **par challenge** (ie. tous les fichiers de ce challenge)
- Archives `.tar.bz2`, `.tar.gz`, `.tar.xz` ou `.zip` lorsque nécessaire. **PAS** de `.rar`, ...
- Compresser (sans tarball, juste via **gzip**[^gz]) les fichiers lorsque c'est utile (memory dump, images BMP, disques, fichiers textes, ...)
- Utiliser `$(split -b 240M -d BIG_FILE BIG_FILE.)` pour uploader les gros fichiers sur owncloud.
  Ces fichiers seront concaténés au moment de leur import sur l'interface.
  Seul le hash du fichier entier est requis dans le fichier `DIGESTS.txt`.

[^gz]: l'intérêt de `gzip` est que le serveur web sera capable de distribuer le fichier sans faire apparaître la compression. Voir le [module nginx utilisé](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html).


### `hints/`

Utilisez ce dossier pour y placer les fichiers que vous mettez à disposition,
dans le cadre d'indices.

Chaque fichier doit avoir une entrée correspondante dans le fichier
`DIGESTS.txt` ; plus d'infos sur la page [`DIGESTS.txt`]({{<relref
"digests">}}).

De plus, chaque fichier doit également posséder une entrée dans le fichier
[`challenge.txt`]({{<relref "challenge">}}), afin de lui attribuer son coût,
titre, ...


### `ressources/`

Rangez dans ce dossier toutes les ressources et scripts que vous avez réalisés
pour le challenge : pour sa construction ou sa résolution, les schémas du SI au
premier challenge concerné, éventuellement un `README.txt` avec les liens des
outils externes.