Guide de contributions aux exercices Progression

Présentation

Progression est un exerciseur conçu pour aider l’apprentissage de la programmation par la pratique. Il permet d’exécuter, analyser et diagnostiquer du code programmé dans le cadre d’un exercice proposé et génère pour l’étudiant une rétroaction immédiate et spécifique.

Fonctionnement

Les questions

L’unité de base marquant la progression de l’étudiant est la question. Il s’agit d’une tâche prévue par l’enseignant et devant être réalisée à l’aide d’un algorithme.

Pour chaque question, l’enseignant procure un énoncé et une ébauche de programme pour un ou plusieurs langages de programmation choisis :

Faites un programme qui affiche 3 fois la chaîne de caractères reçue en entrée

chaîne = input()

# Affiche l'entrée
print( chaîne )

L’étudiant a alors la tâche de compléter l’ébauche afin que son programme réponde à l’énoncé.

L’évaluation

La solution de l’étudiant est validée grâce à une batterie de tests prévue par l’enseignant. Pour chaque test, il aura prévu une entrée envoyée sur l’entrée standard de la solution, ainsi qu’un résultat attendu. La sortie de la solution sur la sortie standard doit être identique au résultat attendu pour chacun des tests pour considérer la solution comme valide.

Exemple de tests pour l’exemple précédent :

    Test 1
    entrée : Bonjour
    sortie :
    Bonjour
    Bonjour
    Bonjour

    Test 2
    entrée : Trois petits tours et puis s'en vont
    sortie :
    Trois petits tours et puis s'en vont
    Trois petits tours et puis s'en vont
    Trois petits tours et puis s'en vont

Création des questions :

Introduction

Créer une nouvelle question à partager dans Progression est aussi simple que d’écrire un fichier texte et le déposer sur un serveur public, là où Progression pourra le récupérer.

Chaque question est constituée d’un ou plusieurs fichiers en format YAML et contient un énoncé, une ou plusieurs ébauches de code et un ou plusieurs tests de validation. Le format complet est décrit ici. Un gabarit est aussi disponible pour vos premières questions.

Consultez la source des questions existantes pour des exemples.

Guide de rédaction

Énoncé

L’énoncé devrait contenir les parties suivantes :

mise en contexte
description des entrées
description des sorties attendues
exemples

Le gabarit proposé fournit chacune de ces parties.

Nomenclature

Pour uniformiser les termes utilisés dans les énoncés, nous recommandons la nomenclature suivante :

Entrée : Les entrées fournies au programme via l’entrée standard.
- Éviter «saisie au clavier»
- Privilégier «reçu en entrée»
Sortie : La sortie textuelle permettant la validation de l’exercice.
- Éviter «afficher»
- Privilégier «produit en sortie»

Indentation

En général, l’indentation devrait être cohérente avec les parties visibles à l’étudiant. Les parties invisibles ne devraient pas influencer l’indentation.

Par exemple, on peut vouloir rendre invisible la définition d’une classe pour éviter la complexité pour l’étudiant :

class  exec {
         
        public static void main( String  args[] ){
                Scanner sc= new Scanner(System.in);

                // +VISIBLE
                // -TODO
                String mot;
                int répétitions;
                // +TODO

        }

Puisque l’étudiant ne voit pas la partie avant +VISIBLE, l’indentation des déclarations de variables ne lui semblera pas cohérente. On devrait l’ajuster de cette façon :

class  exec {
         
public static void main( String  args[] ){
Scanner sc= new Scanner(System.in);

// +VISIBLE
// -TODO
String mot;
int répétitions;
// +TODO

}

Conseils :

Sauf dans les cas les plus simples, au moins 2 tests différents sont nécessaires pour éviter les réponses codées en dur
Attention au formattage des nombres décimaux; le formattage par défaut n’est pas constant d’un langage à l’autre
Sauf si c’est explicitement l’objectif de la question, éviter les invites de saisie. Si elles sont présentes, elles feront partie de la sortie observée et doivent être prévues dans la sortie attendue.

En Java :
- Les classes ne doivent pas être déclarées publiques puisqu’il est impossible de spécifier le nom du fichier où elles se trouvent.

Vérifier la question

Le module python progression_qc permet d’effectuer une validation de la syntaxe d’une question.

Installation

Dans un terminal :

pip install progression_qc

Utilisation

python -m progression_qc <chemin du fichier info.yml>

Documentation

voir : https://git.dti.crosemont.quebec/progression/validateur

Partage des questions

Un simple URL suffit à partager une question avec les utilisateurs. Il suffit de copier et partager l’URL du fichier info.yml ou d’un fichier zip contenant ce fichier et tous les autres fichiers nécessaires. Dans l’interface utilisateur, sélectionnez «Exercices/Ouvrir» et collez l’URL de l’exercice.

D’une manière générale, il suffit de passer le paramètre uri=uri_de_question à Progression, en fournissant une version encodée en Base64 (sans =, avec - et _ comme caractères 63 et 64) de l’URL de la question. Par exemple : https://progression.dti.crosemont.quebec/?uri=aHR0cHM6Ly9wYW5vcmFtaXguZHRpLmNyb3NlbW9udC5xdWViZWMvcy9adzI0ZVk2bjZiOXlBU1IvZG93bmxvYWQ#/question

Une façon plus simple consiste à utiliser un LMS tel que Moodle. Les fichiers constituant l’exercice doivent être disponibles publiquement par HTTPS. Il suffit ensuite de créer une activité « Progression » dans Moodle et fournir un «paramètre personnalisé» src=URL où URL est l’URL du fichier yaml décrivant la question. Plusieurs services permettent de partager les fichiers :

Partager grâce à Gitlab, Github, Bitbucket, etc. : Peut-être la solution la plus simple. Déposez les fichiers dans un dépôt public sur un de ces services et partagez le lien «raw» du fichier info.yml

Github.: Gitlab.:

Par exemple, dans une activité Progression de Moodle, placez dans les paramètres personnalisés l’url src=https://gitlab.com/projet-progression/contenu/prog_1/-/raw/master/questions/01_declarations/01_syntaxe_declarations/1_typage_1/info.yml
Avec Nextcloud : placez le fichier info.yml et ses fichiers «inclus» dans une archive zip et déposez-la sur Nextcloud. Récupérez le lien de partage, ajoutez /download à la fin et c’est ce que vous devez placer dans votre activité Moodle. Exemple : Dans Moodle (paramètres personnalisés ) : src=https://panoramix.dti.crosemont.quebec/s/Zw24eY6n6b9yASR/download
Avec Dropbox : placez le fichier info.yml et ses fichiers «inclus» dans une archive zip et déposez-la sur Nextcloud. Récupérez le lien de partage, remplacez «dl=0» par «dl=1» à la fin et c’est ce que vous devez placer dans votre activité Moodle. Exemple : Dans Moodle (paramètres personnalisés ) : src=https://www.dropbox.com/s/bdqrgfzo4ts5msl/boucle_simple.zip?dl=1
Avec Google : Ça se fait mais c’est un peu plus compliqué. Voir https://www.graytechnical.com/blog/how-to-easily-create-direct-download-links-from-google-drive/ Exemple : src=https://drive.google.com/uc?id=1gUp7srBPm1U1lFIuto8idJhMsUyGtlmn&export=download

Créer une banque de questions

Pour créer une banque complète de questions, une façon simple est de copier un projet existant et ajouter, supprimer ou modifier la liste de questions.

Obtenir les questions communes

Sur Gitlab, créez une divergence du projet commun : https://gitlab.com/projet-progression/contenu/prog_1

Votre divergence (votre projet personnel) aura la même adresse, à l’exception de votre nom d’utilisateur à la place de «progression». Exemple, pour John Doe : https://gitlab.com/jdoe/prog_1
Ajoutez une variable «URL_PROGRESSION» afin de générer des liens qui pointent vers votre instance de Progression.
1. Dans Gitlab, dans le menu «Intégration et livraison continue», développez la section VARIABLE et ajoutez une variable CI/CD nommée URL_PROGRESSION qui contient l’URL de votre instanece, par exemple https://progression.crosemont.qc.ca
  
  ../images/variable_cicd
Dans la page de votre projet, générez une première liste de questions :
1. Dans le menu «Intégration et livraison continue» ou «CI/CD», cliquez sur «Pipelines», «Run pipeline» et le bouton «Run pipeline» en bas.
2. La liste des questions sera créée à l’adresse donnée dans «Exploitation/Pages» ou «Deployments/Pages», selon le modèle https://<nom d'utilisateur>.gitlab.io/<projet>
3. Par la suite, la liste sera automatiquement recrée à chaque modification du projet pour réfléter les changements.
Copiez le paramètre src=URL de la page et coller dans la page paramètres, au niveau des paramètres personnalisés, de votre activité Moodle.

Problèmes rencontrés

À la validation

expected <block end>, but found ’<scalar>’

Problème

progression_qc signale l’erreur :

expected <block end>, but found '<scalar>'
Explication

L’indentation d’un bloc commençant par | ou > est déduite de la première ligne. Dans les cas où l’indentation d’un bloc change de droite à gauche, cette erreur survient.
Solution

Forcer l’indentation par |n ou >n où n est le nombre d’espace d’indentation par rapport au début du bloc :
- Exemple
```
    sortie: |2
         a   
        aaa  
       aaaaa 
      aaaaaaa
```
  La véritable indentation du bloc commence à 2 caractères du mot «sortie», mais la première ligne commence au caractère 5.

À l’exécution en ligne

Error: Request failed with status code 502

Problème

Progression signale l’erreur :

Error: Request failed with status code 502
Explication
La question ne peut pas être chargée.

Problèmes possibles :
- L’URL de la source est incorrecte
- Le fichier info.yml est inaccessible
- Un des fichiers inclus par info.yml est inaccessible par son nom Les liens de partage (par exemple sur Google Drive ou Dropbox) permettent de partager un fichier unique (info.yml), mais pas les fichiers inclus.
Solutions
- Placer toute la question dans un seul fichier, sans inclusion.
- Inclure les fichiers grâce à leur URL public
- Utiliser un mode de partage qui permet l’accès public par nom