Frontend Changesets: Põhjalik juhend versioonihalduseks

Pidevalt arenevas frontend-arenduse maailmas on muudatuste ja väljalasete tõhus haldamine projekti stabiilsuse säilitamiseks ja sujuva koostöö tagamiseks ülioluline. Frontend Changesets pakub võimsat ja paindlikku lahendust versioonihalduseks, sõltuvuste haldamiseks ja väljalaskeprotsessi automatiseerimiseks. See juhend süveneb Frontend Changesets'ide keerukustesse, hõlmates kõike alates põhisätetest kuni täiustatud konfiguratsioonini, pakkudes praktilisi näiteid ja rakendatavaid teadmisi, mis aitavad teil seda olulist tööriista meisterlikult valdama õppida.

Mis on Frontend Changesets?

Frontend Changesets on tööriist, mis on loodud JavaScripti pakettide versioonimise ja avaldamise haldamiseks, eriti monorepodes. See automatiseerib muudatuste logide loomise, pakettide versioonide värskendamise ja avaldamise paketihalduritesse nagu npm. Changesets on sisuliselt väikesed, fokuseeritud failid, mis kirjeldavad konkreetsele paketile või komponendile tehtud muudatusi. Neid faile kasutatakse seejärel väljalaskemärkmete genereerimiseks, pakettide versioonide värskendamiseks ja sõltuvuste haldamiseks.

Võrreldes traditsiooniliste versioonimismeetoditega pakuvad Changesets'id mitmeid olulisi eeliseid:

• Parem koostöö: Changesets'id sujuvdavad koostööprotsessi suurtes projektides, kus on mitu kaastöötajat. Selgelt määratledes iga muudatuse mõju, muudavad Changesets'id meeskonnaliikmetele kaastööde mõistmise ja ülevaatamise lihtsamaks.
• Automatiseeritud väljalasked: Changesets'id automatiseerivad väljalaskeprotsessi, vähendades inimliku eksimuse riski ja tagades ühtlase versioonimise kõigis pakettides.
• Suurem läbipaistvus: Changesets'id pakuvad läbipaistvat ülevaadet kõigist projektis tehtud muudatustest, muutes vigade leidmise ja koodibaasi arengu mõistmise lihtsamaks.
• Monorepo tugi: Changesets'id sobivad eriti hästi monorepode haldamiseks, kus mitu paketti asuvad ühes hoidlas. Need pakuvad tsentraliseeritud ja ühtset lähenemist pakettide versioonimisele ja väljalaskmisele monorepos.

Alustamine Frontend Changesets'idega

Frontend Changesets'ide kasutamise alustamiseks peate installima vajalikud paketid ja lähtestama tööriista oma projektis. Siin on samm-sammuline juhend:

1. Paigaldamine

Paigaldage põhipakett `@changesets/cli` arendussõltuvusena:

            npm install @changesets/cli --save-dev
# või
yarn add @changesets/cli --dev
            

              
                Copy
              
            
          

2. Lähtestamine

Lähtestage Changesets oma projektis, käivitades järgmise käsu:

            npx changeset init
            

              
                Copy
              
            
          

See käsk loob teie projekti juurkausta `.changeset` kataloogi koos konfiguratsioonifailiga (`.changeset/config.json`).

3. Changesets'ide seadistamine

Fail `config.json` võimaldab teil kohandada Changesets'ide käitumist. Siin on tüüpiline konfiguratsioon:

            {
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "ignore": []
}
            

              
                Copy
              
            
          

Vaatame iga valiku üksikasjalikult üle:

• `changelog`: Määrab adapteri, mida kasutatakse muudatuste logi kirjete genereerimiseks. Vaikimisi `@changesets/cli/changelog` adapter kasutab Markdown-vormingut.
• `commit`: Määrab, kas Changesets peaks muudatused automaatselt hoidlasse commit'ima. Selle väärtuseks `false` seadmine võimaldab teil muudatused käsitsi üle vaadata ja commit'ida.
• `fixed`: Massiiv pakettide nimedest, mis tuleks alati koos sama versiooniga välja lasta. See on kasulik tihedalt seotud pakettide puhul.
• `linked`: Massiiv sõltuvustest, mis tuleks arenduse ajal omavahel linkida. See võimaldab teil testida muudatusi mitmes paketis ilma neid avaldamata.
• `access`: Määrab avaldatud pakettide juurdepääsutaseme. Vaikimisi `public` juurdepääsutase muudab paketid npm-is avalikult kättesaadavaks.
• `baseBranch`: Määrab põhiharu (base branch), millega võrreldakse, et teha kindlaks, millised paketid on muutunud. Tavaliselt on see teie hoidla põhiharu (nt `main`, `master`).
• `ignore`: Massiiv failidest või kataloogidest, mida tuleks ignoreerida, kui tehakse kindlaks, millised paketid on muutunud.

Changeset'i loomine

Changeset'i loomiseks käivitage järgmine käsk:

            npx changeset
            

              
                Copy
              
            
          

See käsk palub teil valida paketid, mida on muudetud, ja esitada muudatuste kirjelduse. Kirjeldus peaks olema selge, lühike ja informatiivne, selgitades muudatuste eesmärki ja mõju. Näiteks:

            Parandus: Parandatud viga nupu komponendis, mis põhjustas selle vale kuvamise mobiilseadmetes.

See changeset parandab vea `Button` komponendis, mis põhjustas selle vale stiiliga renderdamise mobiilseadmetes. Probleem oli põhjustatud CSS-i spetsiifilisuse konfliktist. See muudatus lahendab konflikti ja tagab, et nupu komponent kuvatakse korrektselt kõigis seadmetes.
            

              
                Copy
              
            
          

Changesets genereerib seejärel `.changeset` kataloogi Markdown-faili, mis sisaldab teie esitatud teavet. Seda faili kasutatakse hiljem väljalaskemärkmete genereerimiseks ja pakettide versioonide värskendamiseks.

Sõltuvuste haldamine Changesets'idega

Changesets'e saab kasutada ka pakettidevaheliste sõltuvuste haldamiseks monorepos. Changeset'i loomisel saate määrata, millised paketid sõltuvad muudetud paketist. See tagab, et ka sõltuvad paketid värskendatakse, kui muudetud pakett välja lastakse.

Näiteks, kui teil on kaks paketti, `package-a` ja `package-b`, ning `package-b` sõltub `package-a`-st, saate luua `package-a` jaoks Changeset'i ja määrata, et `package-b` sõltub sellest. Kui käivitate `version` käsu (kirjeldatud allpool), värskendab Changesets automaatselt `package-b` versiooni, et see vastaks `package-a` muudatustele.

Versioonimine ja avaldamine

Kui olete loonud ühe või mitu Changeset'i, saate kasutada `version` käsku pakettide versioonide värskendamiseks ja muudatuste logide genereerimiseks.

            npx changeset version
            

              
                Copy
              
            
          

See käsk teeb järgmist:

• Loeb `.changeset` kataloogis olevaid Changeset'e.
• Määrab iga paketi jaoks sobiva versioonitõusu vastavalt Changeset'idele.
• Värskendab `package.json` failid uute versioonidega.
• Genereerib iga paketi jaoks muudatuste logi kirjed.
• Commit'ib muudatused hoidlasse.

Pärast `version` käsu käivitamist saate paketid npm-i avaldada, kasutades `publish` käsku:

            npx changeset publish
            

              
                Copy
              
            
          

See käsk teeb järgmist:

• Ehita paketid (vajadusel).
• Avaldada paketid npm-is.
• Eemaldada Changeset'id `.changeset` kataloogist.

Changesets'ide integreerimine CI/CD-ga

Changesets'id on loodud integreerimiseks CI/CD (pidev integratsioon/pidev tarnimine) torujuhtmetega. See võimaldab teil automatiseerida väljalaskeprotsessi ja tagada, et muudatused rakendatakse kiiresti ja usaldusväärselt.

Siin on tüüpiline CI/CD töövoog Changesets'ide jaoks:

1. Muudatuste commit'imine: Arendajad commit'ivad muudatused hoidlasse, sealhulgas Changeset'id.
2. CI ehitus: CI süsteem käivitab testid ja ehitab projekti.
3. Versioonimine ja avaldamine: CI süsteem käivitab Changesets'ide `version` ja `publish` käsud, et värskendada pakettide versioone, genereerida muudatuste logisid ja avaldada paketid npm-is. Selles etapis kasutatakse sageli automatiseeritud token'it või mandaate npm-i juurdepääsuks.
4. Paigaldamine: CI süsteem paigaldab värskendatud paketid tootmiskeskkonda.

Mitmed CI/CD pakkujad pakuvad sisseehitatud tuge Changesets'idele. Näiteks pakub GitHub Actions spetsiaalse tegevuse Changesets'ide käivitamiseks:

            name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - name: Install dependencies
        run: npm install
      - name: Create Release Pull Request or publish to npm
        id: changesets
        uses: changesets/action@v1
        with:
          # See tagab, et saame token'it lugeda ka siis, kui see pole
          # PR-is saadaval. See hoiab ära vea tekkimise
          # allolevas avaldamise etapis.
          publish: npm run release
          version: npm run version
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

            

              
                Copy
              
            
          

See töövoog käivitab automaatselt `version` ja `publish` käsud iga kord, kui muudatused lükatakse `main` harusse. See loob ka pull request'i, mis sisaldab värskendatud `package.json` faile ja muudatuste logisid.

Täiustatud seadistamine

Changesets pakub mitmeid täiustatud seadistusvalikuid, mis võimaldavad teil tööriista kohandada vastavalt oma konkreetsetele vajadustele. Mõned kõige kasulikumad valikud hõlmavad järgmist:

• Kohandatud muudatuste logi adapterid: Saate luua oma muudatuste logi adaptereid, et genereerida muudatuste logisid vormingus, mis on kohandatud teie projektile.
• Kohandatud versioonimisstrateegiad: Saate määratleda oma versioonimisstrateegiad, et kontrollida, kuidas pakettide versioone tõstetakse.
• Monorepo-spetsiifiline seadistus: Changesets pakub spetsiifilisi seadistusvalikuid monorepode haldamiseks, näiteks võimalust määrata, millised paketid peaksid väljalaskesse kuuluma.

Kohandatud muudatuste logi adapterid

Vaikimisi muudatuste logi adapter kasutab Markdown-vormingut, mis sobib enamiku projektide jaoks. Kui teil on aga vaja genereerida muudatuste logisid teises vormingus, saate luua oma kohandatud adapteri. Kohandatud adapter on lihtsalt JavaScripti moodul, mis ekspordib funktsiooni, mis võtab sisendiks Changeset-objekti ja tagastab stringi, mis sisaldab muudatuste logi kirjet. Siin on näide:

            // my-custom-changelog-adapter.js
module.exports = async function getReleaseLine(changeset, versionType, options) {
  if (changeset.commit) {
    return `- ${changeset.summary} (commit: ${changeset.commit})\n`;
  } else {
    return `- ${changeset.summary}\n`;
  }
};

            

              
                Copy
              
            
          

Oma kohandatud adapteri kasutamiseks peate värskendama `changelog` valikut failis `config.json`:

            {
  "changelog": "./my-custom-changelog-adapter.js",
  ...
}
            

              
                Copy
              
            
          

Kohandatud versioonimisstrateegiad

Changesets kasutab vaikimisi semantilise versioonimise (SemVer) strateegiat, mis tähendab, et pakettide versioone tõstetakse vastavalt tehtud muudatuste tüübile (nt suur, väike, paik). Saate aga määratleda oma versioonimisstrateegiad, et kontrollida, kuidas pakettide versioone tõstetakse. See on kasulik, kui teil on spetsiifilised versioonimisnõuded või kui soovite kasutada teistsugust versioonimisskeemi.

Kohandatud versioonimisstrateegia määratlemiseks peate looma JavaScripti mooduli, mis ekspordib funktsiooni, mis võtab sisendiks Changeset-objekti ja tagastab versioonitõusu tüübi (nt `major`, `minor`, `patch`). Siin on näide:

            // my-custom-versioning-strategy.js
module.exports = async function determineVersion(changeset, options) {
  if (changeset.summary.includes("breaking change")) {
    return "major";
  } else if (changeset.summary.includes("feature")) {
    return "minor";
  } else {
    return "patch";
  }
};

            

              
                Copy
              
            
          

Praegu nõuavad kohandatud versioonimisstrateegiad põhjalikumat seadistamist ja neid ei toetata otse `config.json` kaudu. See on täiustatud kasutusjuhtum ja hõlmab tavaliselt Changesets'i töövoo kohandamist madalamal tasemel.

Frontend Changesets'ide kasutamise parimad tavad

Frontend Changesets'ide eeliste maksimeerimiseks järgige neid parimaid tavasid:

• Kirjutage selgeid ja lühikesi Changeset'i kirjeldusi: Changeset'i kirjeldus on Changeset'i kõige olulisem osa. Veenduge, et kirjutate selgeid, lühikesi ja informatiivseid kirjeldusi, mis selgitavad muudatuste eesmärki ja mõju.
• Kasutage semantilist versioonimist: Järgige semantilise versioonimise põhimõtteid, kui määrate iga paketi jaoks sobiva versioonitõusu. See aitab tagada, et teie pakettide kasutajad saavad iga väljalaske mõjust kergesti aru.
• Automatiseerige väljalaskeprotsess: Integreerige Changesets'id oma CI/CD torujuhtmega, et automatiseerida väljalaskeprotsessi. See vähendab inimliku eksimuse riski ja tagab ühtlase versioonimise kõigis pakettides.
• Vaadake Changeset'id hoolikalt üle: Vaadake Changeset'id hoolikalt üle enne nende liitmist põhiharuga. See aitab vigu tabada ja tagada, et muudatused on nõuetekohaselt dokumenteeritud.
• Hoidke Changeset'id väikesed ja fokusseeritud: Püüdke luua väikesi, fokusseeritud Changeset'e, mis käsitlevad ühte probleemi või funktsiooni. See muudab muudatuste mõistmise ja ülevaatamise lihtsamaks.

Reaalse maailma näited

Paljud populaarsed JavaScripti teegid ja raamistikud kasutavad Frontend Changesets'e versioonimise ja väljalasete haldamiseks. Siin on mõned näited:

• React Aria: Reacti komponentide teek ligipääsetavate kasutajaliideste loomiseks.
• Reach UI: Ligipääsetavate kasutajaliidese primitiivide teek Reacti jaoks.
• Paljud teised avatud lähtekoodiga projektid: Arvukad teised projektid kasutavad Changesets'e selle sujuva väljalaskeprotsessi ja täiustatud koostööfunktsioonide tõttu.

Need projektid on edukalt kasutusele võtnud Changesets'id, et parandada oma väljalaskeprotsessi, tõhustada koostööd ja säilitada läbipaistvat muudatuste ajalugu. Nende kogemused näitavad selle võimsa tööriista väärtust ja mitmekülgsust.

Levinud probleemide tõrkeotsing

Kuigi Changesets'id on üldiselt lihtsad kasutada, võite kokku puutuda mõne levinud probleemiga. Siin on mõned tõrkeotsingu näpunäited:

• `No changesets found`: See viga viitab tavaliselt sellele, et te pole loonud ühtegi Changeset'i või et Changesets pole õigesti seadistatud. Veenduge, et olete loonud vähemalt ühe Changeset'i ja et fail `config.json` on õigesti seadistatud.
• `Version conflict`: See viga ilmneb siis, kui kaks või enam Changeset'i määravad sama paketi jaoks vastuolulisi versioonitõuse. Vaadake Changeset'id üle ja veenduge, et need on järjepidevad.
• `Publish failed`: See viga võib ilmneda mitmel põhjusel, näiteks valed npm-i mandaadid või võrguühenduse probleemid. Kontrollige oma npm-i mandaate ja veenduge, et teil on stabiilne internetiühendus.
• CI/CD integratsiooniprobleemid: Vaadake hoolikalt üle oma CI/CD seadistus, tagades, et vajalikud keskkonnamuutujad (nt `GITHUB_TOKEN`, `NPM_TOKEN`) on õigesti seadistatud ja et Changesets'i käsud täidetakse õiges järjekorras.

Kui teil tekib muid probleeme, lugege ametlikku Changesets'i dokumentatsiooni või otsige abi Changesets'i kogukonnalt.

Kokkuvõte

Frontend Changesets pakub võimsat ja paindlikku lahendust versioonimise ja väljalasete haldamiseks frontend-projektides. Automatiseerides väljalaskeprotsessi, sujuvdades koostööd ja suurendades läbipaistvust, saavad Changesets'id oluliselt parandada teie arendustöövoo tõhusust ja usaldusväärsust. Olenemata sellest, kas töötate väikese isikliku projekti või suuremahulise ettevõtterakenduse kallal, aitavad Changesets'id teil oma koodibaasi tõhusamalt hallata ja pakkuda kasutajatele kvaliteetset tarkvara.

Järgides selles juhendis toodud juhiseid ja parimaid tavasid, saate Frontend Changesets'id meisterlikult selgeks õppida ja kasutada selle täit potentsiaali oma frontend-arenduse töövoo parandamiseks. Võtke Changesets'id omaks ja haarake oma versioonihalduse üle kontroll juba täna!