Vous avez donc fait quelque chose de nouveau et de cool, la pensée vient - mettre en open source et publier en npm.
Il ne suffit pas de pousser le code dans le référentiel public. Cela condamnera le projet à un manque de développement et à un échec. D'autre part, je rappelle un certain nombre de processus ennuyeux: versionner et publier le package, mettre en place une intégration continue, héberger et déployer des pages du projet de démonstration, organiser la possibilité de contribuer pour la communauté.
Si vous vouliez publier un petit paquet, alors cet ensemble de travaux peut faire très peur. Une idée lumineuse pour partager quelque chose d'utile ira dans la longue boîte de cas complexes.
En fait, tout cela peut vous prendre moins d'une heure. Sans connaissance de DevOps et totalement gratuit.
Nous organisons le versioning
Si votre bibliothèque est prête pour la première version, je suggère d'utiliser la version standard . Ce package sera entièrement responsable de la gestion des versions: mettez à jour la version dans package.json, générez le fichier CHANGELOG.md et apposez les balises de version dans git.
Le fichier avec l'historique des modifications est collecté automatiquement par Commissions conventionnelles . Cela apporte un autre avantage: un format de message unifié pour les validations apparaît dans la bibliothèque. Il sera compréhensible à la fois pour vous et pour tout développeur qui a décidé de contribuer à votre projet.
Il n'y a aucune difficulté dans le processus de connexion, il est décrit en détail sur la page github . Ajoutez un ensemble de commandes de version à notre package.json pour plus de commodité:
"release": "standard-version", "release:patch": "npm run release -- --release-as patch", "release:minor": "npm run release -- --release-as minor", "release:major": "npm run release -- --release-as major",
Organiser CI
Pour une intégration continue, je suggère d'utiliser Travis CI . Il est également très convivial:
- Connectez-vous via github
- Sélectionnez votre projet dans la liste et activez Travis pour celui-ci
- Dans le dossier racine du projet, ajoutez une configuration simple qui sera exécutée sur CI:
language: node_js node_js: - "10" script: - npm run lint - npm run build - npm run test:ci
L'IC minimum est prêt. Maintenant, après chaque mise à jour de votre référentiel, Travis exécutera des linters, construira un projet et exécutera des tests.
Vous pouvez regarder l'état des branches, tirer des demandes, analyser le journal de chaque build en cours d'exécution.
Les autres développeurs seront plus confiants dans le passage à votre package s'ils voient que tout votre code a été testé.
Je suggère de déplacer le contrôle sur la couverture du code avec des tests vers le service Coveralls spécialisé. Laissez Travis lui transmettre les résultats du test après chaque génération de CI.
Connectez-vous aux combinaisons et mettez une coche devant le référentiel souhaité. Comme à Travis.
Nous configurons côté projet:
- Installer le package de combinaisons dans la dépendance de développement du projet
- Ajoutez un script pour exécuter des combinaisons, ajoutez-le à la commande de test: ci
"test:ci": "npm run test && npm run coveralls", "coveralls": "cat coverage/lcov.info | coveralls",
Notez que la commande npm run test doit inclure l' --code-coverage . Les combinaisons nécessitent votre fichier lcov.info, qui est généré par votre testeur avec ce drapeau. S'il n'y a pas un tel indicateur, vous pouvez utiliser le package istanbul .
Configurer du côté de Travis:
Si le référentiel est déjà ouvert et restera toujours public, vous pouvez ajouter quelques lignes à .travis.yml:
notifications: webhooks: https://coveralls.io/webhook
Dans tous les autres cas, il est préférable de les connecter via un token:
Accédez aux paramètres du référentiel sur les combinaisons et générez un jeton de dépôt:
Avec ce jeton, accédez aux paramètres du référentiel sur Travis et ajoutez-le à la section Variables d'environnement en tant que COVERALLS_REPO_TOKEN.
Le jeton a lié les deux services. Revenons maintenant à github et protégeons la branche principale du projet avec nos nouveaux outils.
- Allez dans Paramètres -> Branches
- Créez une nouvelle règle pour toutes les branches:
* - Nous mettons les contrôles nécessaires sans lesquels il ne sera pas possible de geler la Pull Request dans la branche master
À ce stade, je suggère également de revenir aux paramètres du référentiel dans les combinaisons. Dans la section PULL REQUESTS ALERTS, vous pouvez spécifier à quel abaissement le niveau de couverture par les tests Pull Request le test ne réussira pas. Faites-le pour que votre colis reste toujours bien testé.
Brossez votre flux de travail
Tout le code du projet doit être conservé dans le même style. Sinon, la base de code se dégradera progressivement et il nous sera plus difficile de soutenir le projet. Il convient également de rappeler que les développeurs externes ne sont pas très intéressés par votre style de code. Pour satisfaire tout le monde, nous nous occuperons de l'automatisation de ce problème.
Au cas où, vérifiez que vous disposez d'un fichier .editorconfig et que les paramètres de formatage du code y sont écrits.
Ensuite, installez quelques autres dépendances de développement: husky et lint-staged . Le premier paquet vous permet de lier des commandes à des hooks git, et le second en conjonction avec lui - exécuter des linters uniquement pour les fichiers ajoutés à la validation.
Par exemple, cela pourrait ressembler à un paramètre pour un package sur TypeScript et moins:
{ ... "scripts": { ... "typecheck": "tsc --noEmit --skipLibCheck", }, "husky": { "hooks": { "pre-commit": "lint-staged && npm run typecheck" } }, "lint-staged": { "*.{js,ts,html,md,less,json}": [ "prettier --write", "git add" ], "*.ts": "tslint", "*.less": "stylelint" } }
Si vous n'avez pas encore configuré de linters, je peux vous conseiller:
- Plus joli pour le formatage du code
- eslint ou tslint comme linters de fichiers JS / TS
- stylelint pour les fichiers de style
Il existe des configurations prédéfinies pour tous, dans lesquelles tous les paramètres de base sont fournis. Par exemple, vous pouvez prendre notre solution clé en main @ tinkoff / linters . La connexion se résume à la création de trois fichiers:
.stylelintrc
{ "extends": ["@tinkoff/linters/stylelint/bases/prettier.stylelint.json"] }
prettier.config.js
module.exports = { ...require('@tinkoff/linters/prettier/prettier.config'), };
tslint.json
{ "extends": ["@tinkoff/linters/tslint/bases/prettier.tslint.json"] }
Publier sur NPM
Il est maintenant temps de publier notre package. Ajoutez une commande simple aux scripts package-json:
"publish": "npm run build && npm publish ./dist"
Dans ce cas, notre référentiel contient du code source et des fichiers pour le développement, et dans npm il y a un paquet compilé dans lequel il n'y a rien de superflu.
Nous collectons l'assemblée actuelle, publions. Le travail est terminé.
Utilisons également les hooks npm et ajoutons un script de post-construction qui copiera README.md dans le dossier d'assembly. Nous n'oublierons donc jamais de mettre à jour la description du package sur NPM.
"build": "..", "postbuild": "node scripts/postbuild.js",
scripts / postbuild.js
const fs = require('fs'); const DIST_LIB_PATH = 'dist/'; const README_PATH = 'README.md'; const PATH_TO = DIST_LIB_PATH + README_PATH; copyReadmeIntoDistFolder(); function copyReadmeIntoDistFolder() { if (!fs.existsSync(README_PATH)) { throw new Error('README.md does not exist'); } else { fs.copyFileSync(README_PATH, PATH_TO); } }
Personnalisez la démo
La démo n'est pas nécessaire pour tous les packages. Si votre package contient quelques méthodes publiques faciles à utiliser et bien documentées, vous pouvez ignorer cette partie en toute sécurité.
Dans d'autres cas, il serait préférable de montrer quelque chose, mais gardez à l'esprit - nous publions la bibliothèque, ce qui signifie que la démo habituelle sur Github Pages ne sera pas aussi intéressante pour les développeurs. Il leur sera plus pratique d'ouvrir immédiatement votre projet de démonstration dans un IDE en ligne: voyez comment le package se connecte, piquez-le ou consultez immédiatement un cas qui les excite.
Vous pouvez créer une démo en tant que référentiel séparé ou la placer dans un nouveau dossier à côté du projet lui-même. Nous n'avons même pas besoin de mettre en place un déploiement! Les IDE en ligne modernes vous permettent de rassembler un projet ou sa branche / dossier séparé directement à partir du github.
Vous pouvez essayer l'un de ces services, cela ne prendra pas plus de cinq minutes:
- stackblitz.com vous permet désormais d'exécuter des projets sur Angular, React, Ionic, TypeScript, RxJs et Svelte. Vous pouvez ouvrir un projet depuis un github en cliquant simplement sur le lien .
- codesandbox.io lance également Angular, React et Vue. Il sait également comment construire du JavaScript simple. Il s'ouvre de la même manière par le lien vers le référentiel, mais un peu plus de détails peuvent être lus ici
- repl.it sur ce service, vous pouvez importer un référentiel avec NodeJS, Express, NextJS, GatsbyJS. Des versions typographiques et vanilla JS sont également disponibles.
Choisissez-en un, ajoutez un lien vers la démo dans README et ne vous en souciez plus. Toutes les modifications seront récupérées automatiquement.
Vous pouvez également ajouter une commande à CI, qui créera une application de démonstration avec la dernière version du package dans NPM. Cela peut être une vérification supplémentaire que la version actuelle du package est correctement lancée sur un projet tiers.
Marafet final
Ajoutez des badges à README.md. Une bagatelle, mais cela vous aidera à vous orienter rapidement vers le visiteur de votre colis sur le github.
Par exemple, voici quatre badges qui indiquent que tout va bien sur le projet et permettent un accès en un clic à sa couverture NPM, CI ou test.
Pour générer des badges, je suggère d'utiliser le service Shields.io . Ils sont simples et de grande qualité.
Total
Un tel ensemble d'outils sera suffisant pour donner un démarrage normal au projet. Un visiteur d'un package dans npm ou d'un référentiel sur un github est plus susceptible de prendre votre package en raison d'une conception appropriée et de la possibilité de l'essayer sur une démo.
Une telle fondation vous permettra d'accepter en toute sécurité des demandes de tirage de l'extérieur, et d'autres développeurs seront plus disposés à la bifurquer. Vous pouvez maintenant vous concentrer sur la mise en œuvre du package lui-même, sans vous soucier des processus entourant son développement.