Beginnen als eerste bijdrager

Voor mij begon het allemaal op Collab Days in België, waar ik Milan Holemans en Jasey Waegebaert ontmoette, 2 geweldige mensen die actief zijn als maintainer op de CLI for Microsoft 365. We spraken een beetje op dit evenement en ze vertelden met groot enthousiasme over wat de CLI for Microsoft 365 allemaal inhoudt. De CLI is geschreven in TypeScript en omdat ik al enkele jaren meer aan client-side development doe, hadden ze mijn aandacht hiermee.

De dag na Collab Days nam ik contact met hen op en konden ze me met groot enthousiasme uitleggen hoe je kunt beginnen als bijdrager aan de CLI for Microsoft 365.

Maak je fork aan

Eerst eerst. Voordat je kunt beginnen, moet je je lokale fork aanmaken.

Op deze fork kun je naar hartenlust dingen wijzigen zonder de upstream-code te beschadigen. Het wordt aanbevolen dat je voor elk issue dat je doet voor de CLI for Microsoft 365 een aparte branch aanmaakt. Op deze manier is elk issue dat je oplost beschermd in één aparte branch.

Wat ook belangrijk is, is dat je de fork die je zojuist hebt aangemaakt lokaal moet pullen. Dit doe je door de link van je github-fork te nemen en deze lokaal te klonen met het commando “git clone”, gevolgd door de url van je fork.

Ga vervolgens met je opdrachtprompt naar de map waar je je fork hebt gekloond en voer het commando npm install uit om de benodigde afhankelijkheden te installeren die de CLI for Microsoft 365 gebruikt. Natuurlijk heb je Node.JS minimaal versie 16 en node package manager minimaal versie 8 nodig.

Voer vervolgens het commando npm build uit om de code te bouwen. En tot slot voer je het commando npm link uit zodat je een verwijzing naar je lokale project aanmaakt.

Let op, want als je de CLI for Microsoft 365 al globaal had geïnstalleerd, moet je deze eerst verwijderen voordat je “npm link” uitvoert. Zodra deze commando’s zijn uitgevoerd, kun je je lokale versie gebruiken wanneer je m365 in je shell gebruikt.

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

Waar te beginnen?

Als je net begint als bijdrager voor de CLI for Microsoft 365, is het het beste om te kijken naar de issues met het label “Good First issue”. Deze issues zijn iets gemakkelijker om mee te beginnen. Je kunt een overzicht maken van alleen de issues met dit label door ergens op het label te klikken,

of gebruik de filter onder “Label”,

of je kunt op deze link klikken.

Daarna kun je door de lijst scrollen en zien welke je het meest interesseren. Als je een issue wilt claimen om op te lossen, is het belangrijk dat dit issue nog niet aan iemand is toegewezen. Je kunt dit zien als er een icoon staat in de kolom “Assignee” naast het issue.

Als je een issue hebt gekozen dat je interesseert, kun je het openen en een reactie achterlaten waarin je aangeeft dat je dat issue wilt claimen en vraagt om je toe te wijzen. Kort nadat je deze reactie op een issue achterlaat, zal een maintainer je toewijzen.

Dit wordt gedaan door een van de 10 maintainers die bereid zijn elke dag een betere versie van de CLI for Microsoft 365 te leveren. Ik had de eer om gedurende enkele maanden met deze mensen samen te werken en ik moet zeggen, het zijn allemaal erg fijne persoonlijkheden om mee te werken. Dit is een van de redenen waarom ik voor het CLI for Microsoft 365 open source-project heb gekozen; dit open source-project is naar mijn mening erg levendig en je krijgt zoveel waardering voor wat je doet.

Soorten issues

Er zijn over het algemeen 4 soorten issues die worden aangemaakt:

• Nieuw Commando: meestal voorgesteld door een van de maintainers. Een nieuw commando is altijd vrij rechtlijnig omdat het altijd met de hele community wordt besproken voordat een nieuw commando wordt opengesteld om te worden opgelost. Bovendien somt een nieuw commando de verschillende opties op die bij het commando horen en legt uit wat het commando moet doen. En soms kan het zijn dat een API al gedocumenteerd is in het issue dat je dan kunt gebruiken om het gewenste resultaat in de uitvoer van het commando weer te geven.

• Verbetering: een bestaand commando dat een bepaalde update moet krijgen. Dit kan een nieuwe optie zijn die toegevoegd moet worden of een bestaande optie die verwijderd of vervangen moet worden.

• Bug: meestal ontdekt door iemand die dit als issue meldt.

• Script: Een PowerShell-script om een bepaald doel te bereiken.

Hoe een nieuw commando te starten

Het eerste wat je moet doen is naar de locatie gaan waar het commando in de repository moet staan; deze zijn gegroepeerd op het werkwoord en vervolgens alfabetisch. Wanneer je de juiste locatie hebt gevonden, maak je 2 bestanden aan in die map. Een .ts-bestand voor het eigenlijke commando en een spec.ts-bestand voor de unit tests.

Het .ts-bestand

Hieronder vind je een voorbeeld van hoe een minimaal .ts-bestand eruitziet voor een commando. Waarbij inline commentaar uitlegt waarvoor elk onderdeel is.

  // 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();

Het .spec-bestand

Het spec.ts-bestand bevat de unit tests voor het commando. Het is belangrijk dat deze tests altijd 100% codedekking garanderen, want de CLI for Microsoft streeft naar niets minder. Het schrijven van deze tests was nieuw voor mij en creëerde een leercurve. Maar ik moet zeggen dat ik veel baat heb gehad bij Martin Linstuyls blog blimped.nl, waar hij op een duidelijke manier uitlegt hoe je deze tests het beste kunt gebruiken en schrijven.

Documentatie

Last but not least: Documentatie. Elk commando heeft zijn documentatie.

Dit wordt gebruikt om een duidelijke documentatiedatabase te hebben op de CLI for Microsoft 365-website. De documentatie bevindt zich in de “docs”-map van de repository, ook gerangschikt op hun werkwoord en vervolgens alfabetisch.

Het is ook belangrijk dat deze documentatie is opgenomen in de inhoudsopgave en dit doe je door het pad toe te voegen aan het mkdocs.yml-bestand.

Publiceer het!

Zodra je klaar bent en alles nogmaals hebt gecontroleerd, kun je je branch committen en publiceren naar je fork op GitHub. Vervolgens ga je naar je GitHub-fork en maak je een nieuw pull request aan. Door een pull request te maken, geef je aan dat je bepaalde stukken code wilt samenvoegen met de hoofdcode van de CLI. Dat kun je uiteraard niet rechtstreeks doen, maar via een pull request laat je de maintainers dit voor je doen. In de titel van het pull request geef je een korte beschrijving. Bijvoorbeeld “adds command…” of “enhances command…”, gevolgd door het commando en afgesloten met een hekje gevolgd door de 4 cijfers van het issue.

Je doet hetzelfde in het beschrijvingsveld met een iets langere uitleg, aangevuld met eventuele opmerkingen als die er zijn. Maar ook in de beschrijving moet je een hekje schrijven met de 4 cijfers van het issue. Dit zorgt ervoor dat de PR gekoppeld wordt aan het issue.

Zodra de PR is aangemaakt, wacht je totdat een van de maintainers zich geroepen voelt om je PR te controleren. Bij het controleren van je PR zullen ze nagaan of er al dan niet verbeteringen of fouten in zitten. Als dat het geval is, zullen ze wijzigingen in je PR aanvragen en je PR omzetten naar conceptmodus. Je kunt deze wijzigingen dan aanbrengen, elke wijziging als opgelost markeren en wanneer je klaar bent, kun je je PR markeren als “gereed voor beoordeling”. Zodra de maintainers vinden dat je PR compleet is, zullen ze het goedkeuren en kort daarna samenvoegen met de hoofdcode van de CLI.

Dit blogbericht is een geschreven versie van de sessie gegeven tijdens de Microsoft Viva Connections & SharePoint Framework Community call. De slides van deze sessie zijn te vinden hier.