Le guide du hacker iSTOA

$Date: 2008-12-04 18:38:21 +0100 (jeu 04 déc 2008) $

Pour optimiser les échanges entre développeurs, utilisateurs, contributeurs, nous présentons ici un ensemble d'indications et de consignes pour le hacker iSTOA.

La gestion du projet iSTOA est assurée par deux outils :

  1. SqueakSource pour la gestion du code source.
  2. GForge@INRIA, l'aggrégateur de projet de l'INRIA pour la gestion du site web, des listes de diffusion, de la documentation, des packages, etc.

Table des matières

Organisation du code source

Pour la gestion du code source de iSTOA nous utilisons SqueakSource car il est optimisé pour gérer du code source Smalltalk/Squeak. Les systèmes de gestion de versions de source tel que SVN ne sont pas adaptés pour cela. Nous utilisons ce dernier uniquement pour gérer les pages web et la documentation.

Le dépôt du source est en accès libre en lecture, en revanche son accès en écriture est limité aux seuls commis du projet. Le code source est organisé en paquets :

  • iStoaCore, le coeur de iSTOA avec les différents modèles, les classes supports, extensions, la base de données.
  • iStoaArtifact, la banque d'artefacts, à savoir des morph pour simuler différentes sortes d'objets pédagogiques.
  • iStoaExo, la banque d'exercices interactifs. Ce paquet dépend de iStoaArtifact.
  • iStoaEtayage, la banque d'étayages pédagogiques, à savoir l'organisation des exercices en groupe selon une progression et un guidage donnés. Ce paquet dépend de iStoaCore, iStoaArtifact et iStoaExo.
  • iStoaWeb, la console du maître. Ce paquet dépend de iStoaCore, iStoaArtifact, iStoaExo et iStoaEtayage.
  • iStoaTestsCore et iStoaTestsExo, un ensemble de tests unitaires sur le coeur du système et les exercices interactifs.
Depuis votre image, configurer Monticello pour qu'il télécharge et installe les sources ci-dessus de iSTOA depuis le SqueakSource. Si vous utilisez l'environnement que nous proposons dans la page TÉLÉCHARGER, celui-ci est déjà préconfiguré pour accéder aux dépôts de code source sur SqueakSource.

Style de programmation

La lecture du livre Smalltalk with Style est fortement recommandé. Vous trouvez d'autres livres Smalltalk dans la page LIENS. Nous rappelons ci-dessous quelques unes de ces règles.

Convention sur les noms de classe, message,...

  • Les noms de classe, variable et message doivent être en anglais.
  • Les noms de classe doivent être préfixés avec IFI et commencer par une majuscule : IFIEtayage.
  • IFI est le nom de domaine de iSTOA pour eviter des conflits de nom de classes avec le système ou d'autres applications. Historiquement IFI est la contraction de iFichier, nom de code du projet avant sa sortie publique.

  • Les noms de variables de classe commencent par une majuscule.
  • Les noms de messages, de variables temporaires et d'instances commencent par une minuscule.
  • Les noms en plusieurs mots doivent être accolés avec une majuscule : IFIOpenExercice pour un classe, openExercice:with: pour un nom de message, learnerEtayage pour une variable d'instance ou temporaire.

Les méthodes doivent être courtes et ne traiter qu'un seul problème à la fois. Si nécessaire découpez en autant de méthodes que de problèmes traités.

Contribuer du code

Soumettre des changeset

La soumissions de rustines (patch) se font par l'envoi de changeset directement sur la liste istoa-project [AT] lists.gforge.inria.fr, avec comme sujet [changeset]. Vous n'avez pas besoin d'être abonné à la liste pour cela.

Votre changeset ne doit traiter qu'un seul type de problème. Si vous traitez plusieurs problèmes, découpez votre changeset de façon à ce que chacun ne traite qu'un seul problème et envoyez autant de courriers séparés.

Documentez la modification apportée, et si nécessaire le numéro de bug couvert dans le système de suivi.

Si le changeset implémente une nouvelle fonctionnalité, documentez la dans votre mél.

Le changeset sera ensuite scruté par une ou plusieurs personnes de la liste. Éventuellement, il vous sera demandé d'apporter des améliorations. A l'issue une personne ayant un droit d'écriture dans le dépôt des sources (un commis), intégrera votre changeset dans iSTOA.

Accès en écriture au dépôt source

Après avoir soumis quelques changeset non triviaux, les commis pourront vous proposer de devenir commis à votre tour, et vous garantir ainsi un accès direct en écriture au dépôt source.

Gestionnaire de projet

Nous utilisons l'aggrégateur de projet GForge@INRIA pour organiser la gestion du projet : pages web, listes de diffusion, espace de téléchargement, reports, suivis de bugs, etc. Si vous souhaitez parcticiper à l'élaboration des web pages, aider à la maintenance des paquets de l'espace téléchargement, suivre les bugs, etc. vous devez devenir membre du projet sur GForge de iSTOA.net.

Pour devenir membre du projet, enregistrez-vous et faites votre demande d'intégration au projet sur la liste istoa-project@lists.gforge.inria.fr.

Créer des artefacts

Un artefact est un objet graphique, interactif ou non, modélisant un ou des objet(s) réel(s), un concept, une simulation. Cela peut être une chose aussi complexe qu'un système d'association ou un micro monde -- par exemple un canevas de géométrie interactive -- ou plus simplement un dé à jouer.

Les artefacts n'ont pas de contenu pédagogique propre, c'est le rôle des exercices qui combinent les artefacts en fonction d'un objectif pédagogique donné. Par exemple, ci-dessous, plusieurs artefacts sont assemblés dans cet exercice pour simuler un jeux de jetons et de boîtes pour compter :

Créer un artefact revient à définir de nouveaux Morph. Selon la complexité de l'artefact, cela peut-être un seul nouveau Morph ou bien plusieurs dizaines. Mais il est préférable de commencer par des choses simples, et n'hésitez pas à demander conseil sur la liste de discussion en cas de doute, nous serons heureux de vous aider.

Créer des exercices

Comment est organisé un exercice ? Quelles classes interviennent dans sa création ? Quelle est l'interface d'un exercice ? Nous essayons dans cette section de répondre à ces questions. Si vous avez d'autres interrogations sans réponse, demandez sur la liste de discussion, nous serons heureux d'y répondre.

Un exercice est toujours organisé avec deux instances de classe. Une instance de sous-classe de IFIExercice qui est le modèle de l'exercice régissant son comportement général. Une instance de sous-classe de IFIExoMorph qui est la représentation graphique du modèle d'exercice, elle s'appelle aussi vue de l'exercice. Ainsi pour un exercice donné, correspond toujours deux classes, c'est un choix qui est a respecter absolument. Un couple modèle-vue de type proxy (pattern) est également disponible. Avec, un exercice est basé sur des classes d'autres exercices.

Le modèle d'un exercice

Pour créer le modèle d'un type d'exercice, vous devez définir une sous classe de la classe abstraite IFIExercice. Cette dernière définit les caractéristiques communes des exercices. Ses variables d'instance sont :

  • view est la vue de l'exercice, c'est à dire un type de Morph, sous classe de IFIExoMorph.
  • counter est le temps alloué en seconde pour réaliser l'exercice, 0 indique pas de limite.
  • startTime est la date à la quelle l'apprenant a commencé l'exercice.
  • endTime est la date à la quelle l'apprenant a terminé l'exercice.
  • seed est une graine (SmallInteger) de génération de nombre aléatoire. Avec cette graine et un exercice donné, il est possible de régénérer un exercice dans les mêmes conditions initiales.
  • random est un générateur de nombres aléatoires qui est initialisé avec seed.
  • help est une aide interactive (non utilisé).
  • objective sont des consignes de l'exercice (non utilisé).

Les méthodes d'instance importantes sont :

  • isSuccess indique par un booléen si l'exercice, dans son état courant, est réussi
  • showErrors demande à sa vue d'afficher, si possible, les erreurs dans l'exercice.
  • seed: permet d'indiquer quelle graine de génération de nombre aléatoire utiliser. Si votre exercice contient des éléments aléatoires, en précisant toujours la même graine, la génération aléatoire de votre exercice sera toujours la même.
  • la catégorie de méthode chronograph contient des méthodes pour initialiser et manipuler le chronographe.
  • chronographAtZero est automatiquement appelée lorsque le chronographe atteint zéro.
  • exerciceDone est appelée lorsque l'apprenant a cliqué le bouton fini ou bien lorsque le chronographe atteint zéro.

La vue d'un exercice

La vue d'un exercice est référencée dans son modèle, dans la variable d'instance de classe view. La vue d'un exercice est une instance d'une sous-classe de IFIExoMorph. Dans une telle vue, il existe plusieurs mécanismes pour construire le contenu de l'exercice. Par défaut, vous pouvez empiler des morph dans une zone appelée playfield, il existe quelques méthodes pour cela. En général vous empilez des artefacts pédagogiques, qui sont des morphs spécialisés pour un usage pédagogique, ceux-ci ont leur propre paquet source iStoaArtifact

Le graphique ci-dessous montre les principales zones d'une vue d'un exercice avec les variables et messages d'instance concernés :

Nous décrivons ci-dessous ses principales variables d'instance :

  • model c'est le modèle de l'exercice.
  • playfield est un morph dans le quel placer le contenu de l'exercice. Par défaut il contient un layout de type empilement du haut vers le bas, voir la méthode initPlayfield.
  • chronograph est un morph d'un chronographe, par défaut il est caché.
  • demoBar est un morph avec boutons pour jouer les étapes de la démonstration.
  • demoRecorder est un morph pour enregistrer/jouer des événements de démonstration.
Dans la partie classe (catégories 'help system' et 'help messages'), il existe un mécanisme d'enregistrement de démonstration qui peut être rejoué par l'utilisateur en cliquant sur le bouton 'Consignes'. Ce mécanisme permet également de créer et enregistrer la démonstration.

Les méthodes d'instance les plus intéressantes sont :

  • addToPlayfield: ajoute un morph dans le playfield.
  • installQuestion: installe la question/consigne dans la partie haute de l'exercice. La question peut être un texte ou au morph.
  • installVerticalFill insère un espace vertical élastique dans le playfield. C'est utile si vous insérez plusieurs morph dans le playfield et que vous souhaitez les espacer.

Un exemple pas à pas

En attendant de détailler cet exemple vous pouvez examiner les classes du tandem IFIAddPyramidExo et IFIAddPyramidExoMorph, c'est un exemple assez simple à comprendre.