So behalten Sie den Überblick über Ihre angehefteten NPM-Pakete

Wie kann dokumentiert / kommentiert werden, warum package.json-Pakete an bestimmte Versionen gebunden sind? Wie kann man erzwingen, dass niemand sie versehentlich aktualisiert?

In einem großen Projekt, an dem ich arbeite und an dem wir ungefähr 100 npm-Pakete haben, versuchen wir, alle unsere Pakete einmal in ein oder zwei Monaten auf die neuesten Versionen zu aktualisieren, weil:

  • Fehler-, Leistungs- und Sicherheitsproblembehebungen werden ständig ausgeliefert, und wir genießen sie gern.
  • Stellen Sie sicher, dass die Pakete der neuesten Dokumentation auf ihrer Website entsprechen, um Verwechslungen zu vermeiden.
  • Allmähliche Aktualisierungen, die weniger als einen Tag dauern, sind viel sicherer und schneller als umfangreiche Aktualisierungen mit vielen Änderungen an den Bremsen verschiedener Pakete, bei denen eine bestimmte Funktion / Fehlerbehebung erforderlich ist.

Warum sollten Sie ein Paket anheften?

Einige Pakete sind an bestimmte Versionen gebunden. Hier einige Beispiele, warum Pakete angeheftet werden könnten:

  • Bugs / Probleme in einer bestimmten Version
    In diesem Fall können wir das Paket aktualisieren, sobald es behoben ist.
  • Änderungen beim Bremsen, die erhebliche Änderungen in der Anwendung erfordern -
    In diesem Fall öffnen wir ein Ticket für das Paketversions-Update und schätzen, wie es durchgeführt werden soll, wie lange es dauert und priorisieren diese Arbeit. Aber bis jemand damit anfängt, wird das Paket vor diesem Bremswechsel auf eine Version fixiert.
  • Manchmal verzweigen wir uns in ein Paket, um es schnell zu reparieren / anzupassen und die Version dem Repository-Commit des Zweigs zuzuordnen.
    In diesem Fall öffnen wir ein Ticket für die generische Durchführung der Anpassung, um eine Pull-Anfrage für das ursprüngliche Projekt zu öffnen.
    Andernfalls erhalten Sie möglicherweise alle Vorteile, die sich aus dem Verbleib auf den neuesten Versionen dieses Repositorys ergeben.
    Manchmal entscheiden wir uns für ein Versäumnis, weil es schwierig sein kann, dieses Problem auf „saubere Weise“ zu lösen, und für das Projekt keine hohe Priorität hat.
  • Einige Pakete warten aus einem der oben genannten Gründe auf die Aktualisierung anderer Pakete.

Das Problem

Wie können wir diese Gründe dokumentieren / kommentieren / durchsetzen? Es reicht nicht aus, ein Paket festzunageln. Neue Leute oder sogar diejenigen, die ein Paket angeheftet haben, werden sich nicht erinnern, warum es überhaupt angeheftet wurde.

Irgendwann verwendeten wir React 15, als der Großteil der Community zu React 16 wechselte. Wir hatten mehr als 10 Pakete zur Unterstützung angeheftet. Es war ein Durcheinander, bis wir es dokumentierten.

Mögliche Lösungen

Kurz gesagt, ich habe keinen sehr sauberen Weg gefunden, um das Problem zu lösen, aber ich habe einen guten gefunden. Ich hoffe, die Community wird in naher Zukunft etwas Besseres herausbringen. Ich schlug sogar einen Weg vor, dies mit Garn zu erreichen. Wenn Sie einen besseren haben, kommentieren Sie diesen bitte unten und lassen Sie es uns wissen. Ich könnte den Artikel mit Ihren Vorschlägen aktualisieren.

Kommentare in package.json

Dies ist die Lösung, die wir derzeit verwenden:

Wie Sie sehen, fügen wir package.json einfach einen Abschnitt hinzu, der alle Versions-Pins dokumentiert. Es werden keine Werkzeuge verwendet. Dies sind nur Kommentare für die Entwickler, die sich die Datei ansehen.

Es ist nicht perfekt. Nichts hindert einen Entwickler daran, Pakete auf Versionen zu aktualisieren, die er nicht aktualisieren sollte, um später festzustellen, dass bereits Probleme mit diesen neuen Versionen festgestellt wurden.
Außerdem könnte es jemandem tatsächlich gelingen, ein angeheftetes Paket zu aktualisieren und den Kommentarbereich nicht zu aktualisieren, wodurch es veraltet bleibt.

Dies liegt daran, dass diese Kommentare nicht einschränkend sind. Eigentlich habe ich darüber nachgedacht, ein Skript zu schreiben, das die Manipulation von Paketen erzwingt, aber im Moment reichen diese Kommentare für uns aus.

Warum verwenden wir solche tatsächlichen Kommentare nicht ?:

"Abhängigkeiten": {
  "@ rebass / grid": "^ 6.0.0",
  "@ welldone-software / warum-hast-du-gerendert": "^ 3.0.6",
  ...
  // ältere 2 Versionen haben versehentliche Änderungen ",
  // https://github.com/kirill-konshin/next-redux-wrapper / releases / tag / 2.1.0 ",
  // Update bei Veröffentlichung von Version 3 "
  "next-redux-wrapper": "2.0.0",
  ...
},

Sieht gut aus, aber package.json sollte immer ein kanonisches JSON bleiben, auf dessen Inhalt Sie JSON.parse () ausführen können. Bibliotheken, Paketmanager, IDEs und andere Tools erwarten dies. Leider sind Kommentare nicht Teil der JSON-Spezifikation.

JSON5 könnte für diesen Zweck geeignet sein, aber die meisten der oben genannten Tools erwarten noch nicht, dass package.json in diesem Format vorliegt.

Versionen mit Greenkeeper.io fixieren

Dieses Abhängigkeitsmanagement-Tool bietet eine Lösung, die jedoch nur für Benutzer geeignet ist, die es zuerst verwenden.

Es aktualisiert Ihre Pakete automatisch in Ihrem CI. Wenn in Ihrem CI ein Problem auftritt, schlägt der Build fehl und Sie haben die Möglichkeit, die Version des Pakets, das den Fehler verursacht hat, ausfindig zu machen und ein Ticket dafür zu öffnen.

Wenn ein Problem auftritt und das CI dadurch nicht gebremst wird, lassen Sie es durch Hinzufügen von Tests bremsen, und wiederholen Sie die oben beschriebene Vorgehensweise, um dieses Problem zu beheben.

Dies ist eine großartige Teillösung, die jedoch nicht alle Fälle abdeckt, in denen Sie ein oben genanntes Paket anheften möchten.

Dokumentation anderswo

Einige Leute schlugen vor, die Versionierung in readme.md oder im Wiki des Projekts zu dokumentieren. Ich denke, es hat keine Vorteile gegenüber der Dokumentation in package.json Lösung, die ich oben erwähnt habe, aber ich wollte immer noch diese Möglichkeit erwähnen.

Meine RFCS auf Garn

Vor ein paar Monaten habe ich ein RFC für Yarn geöffnet, um Kommentare zu Paketen, einschließlich Versionserzwingung, hinzuzufügen. Ich hoffe, dass es irgendwann umgesetzt wird. Hier ist die Spezifikation, die ich bezüglich der Implementierung eines solchen Merkmals vorgeschlagen habe.

Vielen Dank, dass Sie den Artikel gelesen, abonniert und geteilt haben :)