Débuter en tant que premier contributeur

Pour moi, tout a commencé aux Collab Days en Belgique où j’ai rencontré Milan Holemans et Jasey Waegebaert, 2 personnes formidables qui sont actives en tant que mainteneurs sur la CLI for Microsoft 365. Nous avons discuté lors de cet événement et ils m’ont parlé avec beaucoup d’enthousiasme de ce qu’est la CLI for Microsoft 365. La CLI est écrite en TypeScript et puisque je me suis orienté vers un développement plus côté client depuis plusieurs années, ils ont retenu mon attention avec celle-ci.

Le lendemain des Collab Days, je les ai contactés, et ils ont pu m’expliquer avec grand enthousiasme comment on peut commencer en tant que contributeur sur la CLI for Microsoft 365.

Créer votre fork

Commençons par le commencement. Avant de pouvoir démarrer, vous devez créer votre fork local.

Sur ce fork, vous pouvez modifier les choses à votre guise sans casser le code upstream. Il est recommandé de créer une branche séparée pour chaque issue que vous traitez pour la CLI for Microsoft 365. Ainsi, chaque issue que vous résolvez est protégée dans une branche séparée.

Ce qui est également important, c’est que vous devez cloner localement le fork que vous venez de créer. Vous faites cela en prenant le lien de votre fork github et en le clonant localement avec la commande “git clone”, suivie de l’URL de votre fork.

Ensuite, avec votre invite de commande, accédez au dossier où vous avez cloné votre fork et exécutez la commande npm install pour installer les dépendances utilisées par la CLI for Microsoft 365. Vous avez bien sûr besoin de Node.JS version minimum 16 et de node package manager version minimum 8.

Exécutez ensuite la commande npm build pour compiler le code. Et enfin, exécutez la commande npm link pour créer une référence vers votre projet local.

Attention, si vous avez déjà installé la CLI for Microsoft 365 globalement, vous devez d’abord la désinstaller avant d’exécuter “npm link”. Une fois ces commandes exécutées, vous pouvez utiliser votre version locale lorsque vous utilisez m365 dans votre shell.

   git clone *fork url*
   npm install
   npm build
   npm link

Par où commencer ?

Si vous débutez en tant que contributeur pour la CLI for Microsoft 365, il est préférable de regarder les issues étiquetées “Good First issue”. Ces issues sont un peu plus faciles pour commencer. Vous pouvez créer un aperçu des issues avec uniquement ce label en cliquant sur le label quelque part,

ou en utilisant le filtre sous “Label”,

ou vous pouvez cliquer sur ce lien.

Ensuite, vous pouvez parcourir la liste et voir lesquelles vous intéressent le plus. Si vous souhaitez vous attribuer une issue pour la résoudre, il est important que cette issue ne soit pas déjà assignée à quelqu’un — vous pouvez le voir si une icône apparaît dans la colonne “Assignee” à côté de l’issue.

Si vous avez choisi une issue qui vous intéresse, vous pouvez l’ouvrir et laisser un commentaire indiquant que vous souhaitez vous attribuer cette issue et demander à être assigné. Peu après avoir laissé ce commentaire sur une issue, un mainteneur vous assignera.

Cela sera fait par l’un des 10 mainteneurs qui s’efforcent chaque jour de livrer une meilleure version de la CLI for Microsoft 365. J’ai eu l’honneur de travailler avec ces personnes pendant plusieurs mois et je dois dire qu’elles sont toutes très agréables à côtoyer. C’est l’une des raisons pour lesquelles j’ai choisi le projet open source CLI for Microsoft 365 ; ce projet open source est très vivant à mon avis et vous recevez beaucoup de reconnaissance pour ce que vous faites.

Types d’issues

Il existe généralement 4 types d’issues créées :

• Nouvelle commande : généralement proposée par l’un des mainteneurs. Une nouvelle commande est toujours assez simple car elle est toujours discutée avec toute la communauté avant qu’une nouvelle commande soit ouverte à la résolution. De plus, une nouvelle commande liste les différentes options qui appartiennent à la commande et explique ce que la commande doit faire. Et parfois, une API peut déjà être documentée dans l’issue que vous pouvez alors utiliser pour afficher le résultat souhaité dans la sortie de la commande.

• Amélioration : une commande existante qui doit recevoir une certaine mise à jour. Il peut s’agir d’une nouvelle option à ajouter ou d’une option existante à supprimer ou à remplacer.

• Bug : généralement découvert par quelqu’un qui le signale comme issue.

• Script : un script PowerShell pour atteindre un certain objectif.

Comment démarrer une nouvelle commande

La première chose à faire est d’aller à l’emplacement où la commande doit se trouver dans le dépôt, ceux-ci sont regroupés selon le verbe puis par ordre alphabétique. Lorsque vous avez trouvé le bon emplacement, vous créez 2 fichiers dans ce dossier. Un fichier .ts pour la commande elle-même et un fichier spec.ts pour les tests unitaires.

Le fichier .ts

Ci-dessous vous trouverez un exemple de ce à quoi ressemble un fichier .ts minimal pour une commande, avec des commentaires en ligne expliquant à quoi sert chaque partie.

  // all the imports that the command uses
  import { Logger } from '../../../../cli/Logger';
  import GlobalOptions from '../../../../GlobalOptions';
  import PowerPlatformCommand from '../../../base/PowerPlatformCommand';
  import commands from '../../commands';
  import { validation } from '../../../../utils/validation';

  interface CommandArgs {
    options: Options;
  }

  // all the options the command uses, options with the '?' are optional
  export interface Options extends GlobalOptions {
    environment: string;
    id?: string;
    name?: string;
    flag?: boolean;
  }

  // The classname of the command, is a concatenation of all parts that the command uses. As example, this command is 'm365 pp card get', so the name of the class becomes a concatenation of pp, card & get
  class PpCardGetCommand extends PowerPlatformCommand {

    // the actual name of the command, gets its info from the commands file, so the command knows it is being called when 'm365 pp card get' is executed
    public get name(): string {
      return commands.CARD_GET;
    }

    public get description(): string {
      return 'the description for the command';
    }

    // the default properties that are used when the output 'text' or 'csv' is used
    public defaultProperties(): string[] | undefined {
      return ['name', 'cardid'];
    }

    // the constructor
    constructor() {
      super();

      this.#initTelemetry();
      this.#initOptions();
      this.#initValidators();
      this.#initOptionSets();
    }

    // This function will collect and measure how many times an optional option is used. The mandatory options should not be added to this
    #initTelemetry(): void {
      this.telemetry.push((args: CommandArgs) => {
        Object.assign(this.telemetryProperties, {
          id: typeof args.options.id !== 'undefined',
          name: typeof args.options.name !== 'undefined',
          flag: !!args.options.flag
        });
      });
    }

    // This function defines the options associated with the command. Use '' for mandatory options, '[]' for optional options and when you just use '--option', it defines as a flag
    #initOptions(): void {
      this.options.unshift(
        {
          option: '-e, --environment '
        },
        {
          option: '-i, --id [id]'
        },
        {
          option: '-n, --name [name]'
        },
        {
          option: '--flag'
        }
      );
    }

    // this defines option sets. For example, if you want either id, or name is used as an option for the command but not both at the same time
    #initOptionSets(): void {
      this.optionSets.push(
        { options: ['id', 'name'] }
      );
    }

    // if certain options have to be validated before the command can be executed. For example, an ID that needs to be validated to see if it's a valid guid
    #initValidators(): void {
      this.validators.push(
        async (args: CommandArgs) => {
          if (args.options.id && !validation.isValidGuid(args.options.id as string)) {
            return `${args.options.id} is not a valid GUID`;
          }

          return true;
        }
      );
    }

    // the actual command where all the magic happens
    public async commandAction(logger: Logger, args: CommandArgs): Promise<void> {
      logger.log(args.options);
    }
  }

  module.exports = new PpCardGetCommand();

Le fichier .spec

Le fichier spec.ts contient les tests unitaires pour la commande. Il est important que ces tests garantissent toujours une couverture de code à 100 %, car la CLI for Microsoft ne se satisfait de rien de moins. Écrire ces tests était nouveau pour moi et a créé une courbe d’apprentissage. Mais je dois dire que j’ai beaucoup bénéficié du blog de Martin Linstuyl blimped.nl, où il explique clairement comment utiliser et écrire au mieux ces tests.

Documentation

Dernier point mais non des moindres : la documentation. Chaque commande a sa documentation.

Elle permet d’avoir une base de documentation claire sur le site web de la CLI for Microsoft 365. La documentation se trouve dans le dossier “docs” du dépôt, également organisée selon leur verbe puis par ordre alphabétique.

Il est également important que cette documentation soit incluse dans la table des matières, ce que vous faites en ajoutant le chemin au fichier mkdocs.yml.

Publier !

Une fois terminé et tout vérifié à nouveau, vous pouvez commiter et publier votre branche sur votre fork dans github. Ensuite, allez sur votre fork github et créez une nouvelle pull request. En créant une pull request, vous indiquez que vous souhaitez fusionner certains morceaux de code avec le code principal de la CLI. Bien sûr, vous ne pouvez pas le faire directement, mais via une pull request vous permettez aux mainteneurs de le faire pour vous. Dans le titre de la pull request, vous donnez une courte description. Par exemple “adds command…” ou “enhances command…”, suivi de la commande et terminé par un signe de rail suivi des 4 chiffres de l’issue.

Vous faites de même dans le champ de description avec une explication légèrement plus longue, accompagnée de remarques éventuelles. Mais dans la description également, vous devez écrire un signe de rail avec les 4 chiffres de l’issue. Cela permet de lier la PR à l’issue.

Une fois la PR créée, vous attendez qu’un des mainteneurs se sente appelé à vérifier votre PR. Lors de la vérification, ils examineront s’il y a des améliorations ou des erreurs. Si c’est le cas, ils demanderont des modifications à votre PR et convertiront votre PR en mode brouillon. Vous pouvez alors effectuer ces modifications, marquer chaque changement comme résolu et, une fois terminé, marquer votre PR comme “ready for review”. Une fois que les mainteneurs estiment que votre PR est complète, ils l’approuveront et la fusionneront avec le code principal de la CLI peu après.

Cet article de blog est une version écrite de la session donnée lors de l’appel communautaire Microsoft Viva Connections & SharePoint Framework. Les diapositives de cette session peuvent être trouvées ici.