Repository: conventional-commits/conventionalcommits.org Branch: master Commit: 7d293dc59e88 Files: 121 Total size: 653.5 KB Directory structure: gitextract_w3upijgj/ ├── .gitignore ├── .node-version ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── Dockerfile ├── Dockerfile.dev ├── LICENSE ├── Makefile ├── README.md ├── _redirects ├── archetypes/ │ ├── about.md │ ├── next.md │ ├── v1.0.0-beta.1.md │ ├── v1.0.0-beta.2.md │ ├── v1.0.0-beta.3.md │ ├── v1.0.0-beta.md │ └── v1.0.0.md ├── config.yaml ├── content/ │ ├── about/ │ │ └── index.md │ ├── next/ │ │ └── index.md │ ├── v1.0.0/ │ │ ├── index.ar.md │ │ ├── index.be.md │ │ ├── index.bn.md │ │ ├── index.de.md │ │ ├── index.es.md │ │ ├── index.fr.md │ │ ├── index.gr.md │ │ ├── index.hi.md │ │ ├── index.hy.md │ │ ├── index.id.md │ │ ├── index.it.md │ │ ├── index.ja.md │ │ ├── index.ko.md │ │ ├── index.md │ │ ├── index.ml.md │ │ ├── index.nl.md │ │ ├── index.pl.md │ │ ├── index.pr.md │ │ ├── index.pt-br.md │ │ ├── index.ro.md │ │ ├── index.ru.md │ │ ├── index.si.md │ │ ├── index.sr.md │ │ ├── index.ta.md │ │ ├── index.th.md │ │ ├── index.tr.md │ │ ├── index.uk.md │ │ ├── index.uz.md │ │ ├── index.zh-hans.md │ │ └── index.zh-hant.md │ ├── v1.0.0-beta/ │ │ ├── index.it.md │ │ ├── index.md │ │ ├── index.pl.md │ │ └── index.zh-hans.md │ ├── v1.0.0-beta.1/ │ │ ├── index.it.md │ │ ├── index.md │ │ ├── index.pl.md │ │ └── index.zh-hans.md │ ├── v1.0.0-beta.2/ │ │ ├── index.es.md │ │ ├── index.fr.md │ │ ├── index.it.md │ │ ├── index.md │ │ ├── index.pl.md │ │ ├── index.ru.md │ │ └── index.zh-hans.md │ ├── v1.0.0-beta.3/ │ │ ├── index.es.md │ │ ├── index.fr.md │ │ ├── index.hy.md │ │ ├── index.it.md │ │ ├── index.md │ │ ├── index.pt-br.md │ │ ├── index.ru.md │ │ └── index.zh-hans.md │ └── v1.0.0-beta.4/ │ ├── index.fr.md │ ├── index.hy.md │ ├── index.id.md │ ├── index.it.md │ ├── index.ja.md │ ├── index.ko.md │ ├── index.md │ ├── index.pt-br.md │ ├── index.ru.md │ ├── index.zh-hans.md │ └── index.zh-hant.md ├── data/ │ └── .gitkeep ├── docker-compose.yml ├── layouts/ │ └── .gitkeep ├── static/ │ └── .gitkeep └── themes/ └── conventional-commits/ ├── .editorconfig ├── .gitignore ├── LICENSE ├── README.md ├── archetypes/ │ └── default.md ├── layouts/ │ ├── 404.html │ ├── _default/ │ │ └── single.html │ ├── about/ │ │ └── single.html │ ├── partials/ │ │ ├── footer.html │ │ ├── head.html │ │ ├── header.html │ │ ├── mini_welcome.html │ │ ├── scripts.html │ │ ├── svg-github.html │ │ └── welcome.html │ └── shortcodes/ │ └── banner-image.html ├── package.json ├── static/ │ ├── css/ │ │ └── scss/ │ │ ├── abstracts/ │ │ │ ├── _functions.scss │ │ │ ├── _mixins.scss │ │ │ ├── _variables.scss │ │ │ └── index.scss │ │ ├── base/ │ │ │ └── _base.scss │ │ ├── components/ │ │ │ ├── _banner-image.scss │ │ │ └── _dropdown.scss │ │ ├── layout/ │ │ │ ├── _footer.scss │ │ │ ├── _header.scss │ │ │ └── _welcome.scss │ │ ├── style.scss │ │ ├── themes/ │ │ │ ├── _conventional-commits.scss │ │ │ └── _markdown.scss │ │ └── vendors/ │ │ └── github-markdown-css.scss │ └── js/ │ └── index.js └── theme.toml ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ public/ .idea/ ================================================ FILE: .node-version ================================================ 19.0.0 ================================================ FILE: CODE_OF_CONDUCT.md ================================================ # Contributor Covenant Code of Conduct ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: * Using welcoming and inclusive language * Being respectful of differing viewpoints and experiences * Gracefully accepting constructive criticism * Focusing on what is best for the community * Showing empathy towards other community members Examples of unacceptable behavior by participants include: * The use of sexualized language or imagery and unwelcome sexual attention or advances * Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or electronic address, without explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at bencoe@gmail.com or damianopetrungaro@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] [homepage]: http://contributor-covenant.org [version]: http://contributor-covenant.org/version/1/4/ ================================================ FILE: CONTRIBUTING.md ================================================ # How to Contribute The contribution guideline is derived from the SlimPHP, Istanbul Code Coverage and Ruby contribution guideline ## Contributor Behavior Be kind to one another. We're striving to make Conventional Commits an inclusive environment that's great for first time open-source contributors. tldr; we value constructive community interaction, over technical acumen. ## Pull Requests Conventional Commits use the [GitHub flow](https://guides.github.com/introduction/flow/) as main versioning workflow 1. Fork the Conventional Commits repository 2. Create a new branch for each feature, fix or improvement 3. Send a pull request from each feature branch to the **master** branch It is very important to separate new features or improvements into separate feature branches, and to send a pull request for each branch. This allow us to review and pull in new features or improvements individually. ## Style Guide All pull requests SHOULD adhere to the [Conventional Commits specification](https://conventionalcommits.org/) ## License You must agree that your patch will be licensed under the Conventional Commit License, and when we change the license we will assume that you agreed with the change unless you object to the changes in time. ================================================ FILE: Dockerfile ================================================ FROM node:19.0.0-alpine WORKDIR /src/ COPY ./themes/conventional-commits /src/ RUN apk add make RUN npm install RUN npm run build FROM jguyomard/hugo-builder:latest COPY ./ /src/ COPY --from=0 /src/ /src/themes/conventional-commits/ RUN hugo FROM nginx:stable COPY --from=1 /src/public/ /usr/share/nginx/html/ EXPOSE 80 ================================================ FILE: Dockerfile.dev ================================================ FROM jguyomard/hugo-builder:latest FROM node:19.0.0-alpine WORKDIR /src/ COPY --from=0 /usr/local/bin/hugo /usr/local/bin/hugo COPY ./ /src/ RUN apk add make ENTRYPOINT make all-dev EXPOSE 1313 ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2018 Conventional Changelog Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: Makefile ================================================ all: compile-assets compile-site all-dev: compile-assets-dev serve-site-dev compile-site: echo "Generating static website" hugo echo "Website generated" serve-site-dev: echo "Serving website" hugo serve --bind=0.0.0.0 compile-assets: echo "Compiling assets" cd themes/conventional-commits && npm install && npm run build echo "Assets compiled" compile-assets-dev: echo "Compiling assets" cd themes/conventional-commits && npm install && npm run start & ================================================ FILE: README.md ================================================ # ConventionalCommits.org [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) This repo is the home of the [Conventional Commits specification](https://www.conventionalcommits.org/). ## Repo Layout We use [HUGO](https://gohugo.io/) as static site generator, so we use the [directory structure](https://gohugo.io/getting-started/directory-structure/) HUGO proposes. #### Our implementation * `./content`: contains all the versions of the specification. * `./content/next/`: contains the version of the specification (where all the changes SHOULD be made). * `./content/**/index.[lang].md`: contains the content of the specification, if a language is specified it's a translation. ## Contributing We'd love your help refining the language of this specification, fixing typos, or adding more translations. Please don't hesitate to send a pull request. ### Adding a translation 1. Create a new file in `./content/version/index.[lang].md` using the hugo command `hugo new [version]/index.[lang].md`. 1. Ensure all files have the appropriate fields required (see others as an example).. 1. Add the language to the `config.yaml` file (see others as an example). ### Running project locally There's a docker-compose.yml file ready that will help you to check if the website looks good! To run it make sure you have [docker-compose installed](https://docs.docker.com/compose/install/#install-compose) on your machine and just use the command `docker-compose up` to make it run locally. Once the website will be compiled, you can see the website visiting `http://localhost:1313` ## Badges! Tell your users that you use the Conventional Commits specification: ```markdown [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) ``` ## Thank you To **[Lorenzo D'Ianni](https://github.com/lorenzodianni)** for the great effort creating the CSS and the HTML for the new UI. To **[Netlify](https://www.netlify.com/)** to host our project, giving us a lot of [amazing built in functionality](https://www.netlify.com/features/) for free. To **[semver.org](https://github.com/mojombo/semver.org)**: we used [semver.org](https://github.com/mojombo/semver.org) as a blueprint for the structure of this specification and the first version of the website. ================================================ FILE: _redirects ================================================ / /en/v1.0.0/ ================================================ FILE: archetypes/about.md ================================================ --- type: about draft: true --- ================================================ FILE: archetypes/next.md ================================================ --- draft: true --- ================================================ FILE: archetypes/v1.0.0-beta.1.md ================================================ --- draft: false --- ================================================ FILE: archetypes/v1.0.0-beta.2.md ================================================ --- draft: false --- ================================================ FILE: archetypes/v1.0.0-beta.3.md ================================================ --- draft: false --- ================================================ FILE: archetypes/v1.0.0-beta.md ================================================ --- draft: false --- ================================================ FILE: archetypes/v1.0.0.md ================================================ --- draft: false --- ================================================ FILE: config.yaml ================================================ baseURL: '/' languageCode: en-us theme: conventional-commits defaultContentLanguageInSubdir: true defaultContentLanguage: "en" # Global parameters params: license: title: License action: label: Creative Commons - CC BY 3.0 url: 'https://creativecommons.org/licenses/by/3.0/' footer: logos: - name: github url: 'https://github.com/conventional-commits/conventionalcommits.org' # Languages parameters languages: en: weight: 1 languageName: "English" title: Conventional Commits description: A specification for adding human and machine readable meaning to commit messages actions: - label: Quick Summary url: '#summary' - label: Full Specification url: '#specification' - label: Contribute url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 - v1.0.0-beta.3 - v1.0.0-beta.2 - v1.0.0-beta.1 - v1.0.0-beta it: weight: 2 languageName: "Italian" title: Commit Convenzionali description: Una specifica per aggiungere un significato leggibile da umani e macchine ai messaggi dei commit actions: - label: Riepilogo url: '#riepilogo' - label: Leggi la specifica url: '#specifica' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 - v1.0.0-beta.3 - v1.0.0-beta.2 - v1.0.0-beta.1 - v1.0.0-beta pl: weight: 3 languageName: "Polish" title: Conventional Commits description: Specyfikacja, nadająca czytelność commitom zarówno dla ludzi, jak i maszyn actions: - label: Przeczytaj specyfikację url: '#specyfikacja' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.2 - v1.0.0-beta.1 - v1.0.0-beta # zh-cn/zh-tw/zh-chs are legacy # zh-hans specification usage from IETF language tag # check https://www.ietf.org/rfc/rfc4646.txt zh-hans: weight: 4 languageName: "简体中文" title: 约定式提交 description: 一种用于给提交信息增加人机可读含义的规范 actions: - label: 阅读规范 url: '#约定式提交规范' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 - v1.0.0-beta.3 - v1.0.0-beta.2 - v1.0.0-beta.1 - v1.0.0-beta zh-hant: weight: 5 languageName: "繁體中文" title: 慣例式提交 description: 一種用於增加提交說明之人機可讀性意義的規範 actions: - label: 概述 url: '#概述' - label: 完整規範 url: '#規範' - label: 貢獻 url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 es: weight: 6 languageName: "Spanish" title: Commits Convencionales description: Especificación para dar significado a los mensajes de los commits haciéndolos legibles para máquinas y humanos actions: - label: Lee la especificación url: '#especificación' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0-beta.3 list: - v1.0.0-beta.3 - v1.0.0-beta.2 ru: weight: 7 languageName: "Русский" title: Соглашение о коммитах description: Простое соглашение о том, как нужно писать сообщения коммитов actions: - label: Главное url: '#главное' - label: Спецификация url: '#спецификация' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 - v1.0.0-beta.3 - v1.0.0-beta.2 ja: weight: 8 languageName: "日本語" title: Conventional Commits description: 人間と機械が読みやすく、意味のあるコミットメッセージにするための仕様 actions: - label: 簡単なまとめ url: '#概要' - label: すべての仕様 url: '#仕様' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 fr: weight: 9 languageName: "Français" title: Commits Conventionnels description: Une spécification qui permet une signification lisible pour l'humain et pour la machine dans les messages des commits actions: - label: Spécification complète url: '#spécification' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.2 hi: weight: 10 languageName: "हिन्दी" title: पारंपरिक कमिट (Conventional Commits) description: कमिट संदेशों में मानव और मशीन दोनों के लिए अर्थ जोड़ने की एक विशिष्टता actions: - label: सारांश url: '#summary' - label: पूरी विशिष्टता url: '#specification' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 ko: weight: 10 languageName: "한국어" title: Conventional Commits description: 커밋 메시지에 사용자와 기계 모두가 이해할 수 있는 의미를 부여하기 위한 스펙 actions: - label: 요약 url: '#개요' - label: 전체 스펙 url: '#규격' - label: Github url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0-beta.4 list: - v1.0.0-beta.4 pt-br: weight: 11 languageName: "Português Brasileiro" title: Conventional Commits description: Uma especificação para dar um significado legível às mensagens de commit para humanos e máquinas actions: - label: Resumo url: '#resumo' - label: Especificação Completa url: '#especificação' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 - v1.0.0-beta.3 id: weight: 12 languageName: "Indonesia" title: Komit Konvensional description: Spesifikasi untuk menambahkan makna yang dapat dibaca manusia dan mesin untuk pesan komit actions: - label: Ringkasan url: '#ringkasan' - label: Spesifikasi url: '#spesifikasi' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 - v1.0.0-beta.4 - v1.0.0 hy: weight: 13 languageName: "Հայերեն" title: Համաձայնեցված «Commit»֊ներ description: Սպեցիֆիկացիա, որը ընթեռնելի է դարձնում «commit» մեսիջները մեքենաների և մարդկանց համար actions: - label: Համառոտագիր url: '#համառոտագիր' - label: Սպեցիֆիկացիա url: '#սպեցիֆիկացիա' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0-beta.4 list: - v1.0.0-beta.4 - v1.0.0-beta.3 de: weight: 14 languageName: "Deutsch" title: Konventionelle Commits description: Eine Spezifikation für menschlich und maschinell lesbare Commit-Nachrichten actions: - label: Zusammenfassung url: '#zusammenfassung' - label: Spezifikation url: '#spezifikation' - label: Contribute url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 th: weight: 15 languageName: "ไทย" title: Conventional Commits description: ข้อกำหนดในการทำให้มนุษย์และเครื่องจักรเข้าใจความหมายของข้อความ commit actions: - label: ข้อสรุปอย่างเร็ว url: '#ข้อสรุป' - label: ข้อกำหนดฉบับเต็ม url: '#ข้อกำหนด' - label: มีส่วนร่วม url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 uk: weight: 16 languageName: "Ukrainian - Українська" title: Політика Комітів description: Угода для додавання зручних для читання коміт повідомлень для людей та роботів actions: - label: Швидкий Огляд url: '#summary' - label: Повна Специфікація url: '#specification' - label: Контрибуція url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 be: weight: 17 languageName: "Belarusian - Беларуская" title: Пагадненне аб камітах description: Спецыфікацыя па дадаванню лёгкачытэльных паведамленняў у камітах для людзей і робатаў actions: - label: Сціслы агляд url: '#сціслы-агляд' - label: Поўная Спецыфікацыя url: '#поўная-спецыфікацыя' - label: Github url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 tr: weight: 18 languageName: "Türkçe" title: Conventional Commits description: Conventional Commits şartnamesi, commit mesajları hakkında kolayca takip edilebilecek bir sözleşmedir actions: - label: Özet url: '#özet' - label: Şartname url: '#şartname' - label: Github url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 nl: weight: 19 languageName: "Nederlands" title: Conventionele Commits description: Een specificatie voor mens- en machine-leesbare commit berichten actions: - label: Samenvatting url: '#samenvatting' - label: Specificatie url: '#specificatie' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 ml: weight: 20 languageName: "Malayalam - മലയാളം" title: കോൺവെൻഷനൽ കമ്മിറ്റ്‌സ് description: സന്ദേശങ്ങൾ കമ്മിറ്റ് ചെയ്യാൻ മനുഷ്യനും യന്ത്രവും വായിക്കാവുന്ന അർത്ഥം ചേർക്കുന്നതിനുള്ള ഒരു സ്പെസിഫിക്കേഷൻ actions: - label: സംഗ്രഹം url: '#സംഗ്രഹം' - label: പൂർണ്ണ സ്പെസിഫിക്കേഷൻ url: '#specification' - label: Github url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 ro: weight: 21 languageName: "Romanian" title: Comiteri convenționale description: O specificație pentru adăugarea unui sens care poate fi citit de om și de mașină pentru a comite mesaje actions: - label: Rezumat rapid url: '#rezumat' - label: Specificație completă url: '#specificație' - label: Contribuie url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 bn: weight: 22 languageName: "বাংলা (Bengali)" title: প্রচলিত কমিটসমূহ description: কমিট বার্তায় মানুষ এবং মেশিন দ্বারা পাঠযোগ্য অর্থ যোগ করার জন্য একটি সবিস্তার বিবরণী। actions: - label: সারসংক্ষেপ url: '#সারসংক্ষেপ' - label: নির্দিষ্টকরণ রীতি url: '#নির্দিষ্টকরণ' - label: গিটহাব url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 uz: weight: 23 languageName: "Uzbek (O'zbekcha)" title: Conventional Commits description: Commit xabarlariga inson va mashina o'qishi mumkin bo'ladigan ma'noni qo'shish uchun spesifikatsiya actions: - label: Xulosa url: '#xulosa' - label: Spesifikatsiya url: '#spesifikatsiya' - label: Github url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 ar: weight: 24 languageName: "العربية" title: Conventional Commits description: إضافة معنى قابل للقراءة من قبل الإنسان والآلة إلى رسائل الـ commit. actions: - label: الملخص url: '# الملخص' - label: المواصفات url: '# المواصفات' - label: شارك في المشروع url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 rtl: true ta: weight: 20 languageName: "Tamil - தமிழ்" title: வழக்கமான கமிட்கள் description: செய்திகளை உறுதி செய்வதற்கு மனித மற்றும் இயந்திரம் படிக்கக்கூடிய பொருளைச் சேர்ப்பதற்கான விவரக்குறிப்பு. actions: - label: சுருக்கம் url: '#summary' - label: ஆவண விவரக்குறிப்பு url: '#specification' - label: பங்களிக்கவும் url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 pr: weight: 26 languageName: "فارسی" title: Conventional Commits description: مشخصات برای اضافه کردن معانی خوانا برای اسنان و ماشین به پیام های کامیت actions: - label: خلاصه url: '# خلاصه' - label: توضیحات url: '# توضیحات' - label: مشارکت url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 rtl: true gr: weight: 27 languageName: "Ελληνικά" title: Conventional Commits description: Μια προδιαγραφή για την προσθήκη νοήματος, αναγνώσιμου τόσο από ανθρώπους όσο και από μηχανές, στα μηνύματα των commit actions: - label: Γρήγορη Περίληψη url: "#περίληψη" - label: Πλήρης Προδιαγραφή url: "#προδιαγραφή" - label: Συνεισφέρετε url: "https://github.com/conventional-commits/conventionalcommits.org" versions: current: v1.0.0 list: - v1.0.0 sr: weight: 28 languageName: "Serbian - Srpski" title: Conventional Commits description: Specifikacija za dodavanje značenja porukama commit-ova koje je čitljivo i ljudima i mašinama. actions: - label: Kratak rezime url: '#rezime' - label: Puna specifikacija url: '#specifikacija' - label: Doprinos url: 'https://github.com/conventional-commits/conventionalcommits.org' versions: current: v1.0.0 list: - v1.0.0 si: weight: 29 languageName: "Sinhala" title: සම්මුතිවාදී කමිට්ස් description: මිනිසුන්ට මෙන්ම යන්ත්‍රවලටද තේරුම් ගත හැකි අයුරින් කමිට් පණිවිඩවලට අර්ථයක් ලබා දීම සඳහා වූ පිරිවිතරයකි. actions: - label: සාරාංශය url: '#summary' - label: සම්පූර්ණ පිරිවිතරය url: '#පිරිවිතරය' - label: දායක වන්න ================================================ FILE: content/about/index.md ================================================ --- type: about draft: false --- # About The Conventional Commits specification is inspired by, and based heavily on, the [Angular Commit Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). The first draft of this specification has been written in collaboration with some of the folks contributing to: * [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog): a set of tools for parsing Conventional Commits messages from git histories. * [parse-commit-message](https://npmjs.com/package/parse-commit-message): Extensible utilities for parsing, stringify and validating Conventional Commit messages. * [bumped](https://bumped.github.io): a tool for releasing software that makes it easy to perform actions before and after releasing a new version of your software. * [unleash](https://github.com/netflix/unleash): a tool for automating the software release and publishing lifecycle. * [lerna](https://github.com/lerna/lerna): a tool for managing monorepos, which grew out of the Babel project. ## Tooling for Conventional Commits * [go-conventional-commits](https://github.com/joselitofilho/go-conventional-commits): A tool to parser your git commit messages into a change log message based on conventional commits specification. * [go-conventionalcommits](https://github.com/leodido/go-conventionalcommits): Full Go powers to parse conventional commits. * [go-conventional-commit](https://gitlab.com/digitalxero/go-conventional-commit): go library for parsing commit messages following the specification. * [chglog](https://github.com/goreleaser/chglog): a tool for parsing Conventional Commits messages from git histories and turning them into templateable change logs. * [fastlane-plugin](https://github.com/xotahal/fastlane-plugin-semantic_release): follows the specification to manage versions and generate a changelog automatically. * [commitizen/cz-cli](https://github.com/commitizen/cz-cli): A Node.js tool to create commit messages following the Conventional Commits specs. * [commitizen-tools/commitizen](https://github.com/commitizen-tools/commitizen): A tool written in Python to create committing rules for projects, auto bump versions and auto changelog generation. * [php-commitizen](https://github.com/damianopetrungaro/php-commitizen): A PHP tool built to create commit messages following the Conventional Commits specs. Configurable and usable for PHP projects as a composer dependency or usable globally for non-PHP projects. * [php-conventional-changelog](https://github.com/marcocesarato/php-conventional-changelog): a tool built to generate a changelog from a project's committing history messages and metadata and automate versioning with Semver, following Conventional Commits specs. Configurable and usable for PHP projects as a composer dependency or usable globally for non-PHP projects. * [conventional-commits](https://github.com/ramsey/conventional-commits): A PHP library for creating and validating commit messages according to the Conventional Commits specification. * [sh-conventional-commits](https://github.com/joaobsjunior/sh-conventional-commits) A hook that locally validates commit messages, checking if they follow the conventional commit pattern. The project also includes a shell script for generating semantic versions through conventional commits. * [commitlint](https://github.com/conventional-changelog/commitlint): A linter to check that your commit messages meet the Conventional Commits format. * [gitlint](https://github.com/jorisroovers/gitlint): Git commit message linter written in Python, which can be configured to [enforce Conventional Commits format](https://jorisroovers.com/gitlint/contrib_rules/#ct1-contrib-title-conventional-commits). * [conform](https://github.com/autonomy/conform): a tool that can be used to enforce policies on git repositories, including Conventional Commits. * [detect-next-version](https://npmjs.com/package/detect-next-version): Parse, detect and get more metadata about given Conventional Commits. * [recommended-bump](https://www.npmjs.com/package/recommended-bump): Calculates the recommended version bump based on given Conventional Commits. * [git-commits-since](https://www.npmjs.com/package/git-commits-since): Get all (raw) commits since period or (by default) from latest git SemVer tag, plus plugins support. * [standard-version](https://github.com/conventional-changelog/standard-version): Automatic versioning and CHANGELOG management, using GitHub's new squash button and the recommended Conventional Commits workflow. * [Conventional Commit](https://github.com/lppedd/idea-conventional-commit): provides extensible context and template-based completion, and inspections, for Conventional Commits inside the VCS Commit dialog. Available for all [JetBrains IDEs](https://www.jetbrains.com/). * [Git Commit Template](https://plugins.jetbrains.com/plugin/9861-git-commit-template): Add Conventional Commits support to [JetBrains Editors](https://www.jetbrains.com/) (IntelliJ IDEA, PyCharm, PhpStorm...). * [commitsar](https://github.com/commitsar-app/commitsar): Go tool for checking if commits on branch are Conventional Commits compliant. Comes with Docker image for CI uses. * [semantic-release](https://github.com/semantic-release/semantic-release): A tool that automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package. * [python-semantic-release](https://github.com/relekang/python-semantic-release): Automatic Semantic Versioning for Python projects. This is a Python implementation of the [semantic-release](https://github.com/semantic-release/semantic-release) for Node.js. * [VSCode Conventional Commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits): Add Conventional Commits supports for VSCode. * [Pyhist](https://github.com/jgoodman8/pyhist): A Python utility to automagically update the package version from the git history and generate the Changelog. * [git-mkver](https://github.com/idc101/git-mkver): A tool to automatically apply Semantic Versioning to git repositories based on _Conventional Commits_. * [git-semver](https://github.com/PSanetra/git-semver): A cli tool for calculating the next semantic version according to latest _Conventional Commits_ and printing changelogs to stdout. * [Conventional Commits Next Version](https://gitlab.com/DeveloperC/conventional_commits_next_version): A tooling and language agnostic utility to calculate the next semantic version based on the _Conventional Commits_ since the prior version. Supports monorepos. * [change](https://github.com/adamtabrams/change): A tool for generating and updating a changelog using Conventional Commits. * [Turbogit](https://b4nst.github.io/turbogit): A command line tool to help you follow _Conventional Commits_ flow. * [sv4git](https://github.com/bvieira/sv4git): A command line tool (CLI) to validate commit messages, bump versions, create tags and generate changelogs. * [Versio](https://github.com/chaaz/versio): A monorepo-compatible tool that updates version numbers based on conventional commits and project dependencies. It can generate tags and changelogs, too. * [Git Changelog Lib](https://github.com/tomasbjerre/git-changelog-lib): A Java library that supports rendering a changelog given a context derived from Git. Supports conventional commits with [Handlebars Helpers](https://github.com/tomasbjerre/git-changelog-lib#helpers). It is used in: * [Gradle](https://github.com/tomasbjerre/git-changelog-gradle-plugin) * [Maven](https://github.com/tomasbjerre/git-changelog-maven-plugin) * [Jenkins](https://github.com/jenkinsci/git-changelog-plugin) * [Command Line](https://github.com/tomasbjerre/git-changelog-command-line) * [Docker](https://hub.docker.com/r/tomasbjerre/git-changelog-command-line) * [GitHub Action](https://github.com/tomasbjerre/git-changelog-github-release) * [Cocogitto](https://github.com/oknozor/cocogitto): Cocogitto is a set of cli tools for the conventional commits and semver specifications. * [Conventional Commits Linter](https://gitlab.com/DeveloperC/conventional_commits_linter): A tooling and language agnostic Git commit linter for the _Conventional Commits_ specification. * [Uplift](https://github.com/gembaadvantage/uplift): Semantic versioning the easy way. Powered by Conventional Commits. Built for use with CI. * [Monopub](https://github.com/thi-ng/monopub): Conventional Commits-driven release tool for monorepo releases, versioning & changelog generation. * [git-cliff](https://git-cliff.org/): A highly customizable changelog generator written in Rust that can generate changelog files for any Git repository that follows the _Conventional Commits_ specification * [cz-git](https://github.com/Zhengqbbb/cz-git): A customizable CLI tool for generating commit messages following Conventional Commits. * [EasyBuild ecosystem](https://github.com/easybuild-org): A collection of tools for automating release using Conventional Commits. * [EasyBuild.CommitLinter](https://github.com/easybuild-org/EasyBuild.CommitLinter): A .NET CLI tool to lint your commit messages * [EasyBuild.ChangelogGen](https://github.com/easybuild-org/EasyBuild.ChangelogGen): A .NET CLI tool for generating changelog based on Git history following Conventional Commits. ## Projects Using Conventional Commits * [NFPM](https://github.com/goreleaser/nfpm): NFPM is Not FPM - a simple deb, rpm and apk packager written in Go. * [yargs](https://github.com/yargs/yargs): everyone's favorite pirate themed command line argument parser. * [istanbuljs](https://github.com/istanbuljs/istanbuljs): a collection of open-source tools and libraries for adding test coverage to your JavaScript tests. * [uPortal-home](https://github.com/UW-Madison-DoIT/angularjs-portal) and [uPortal-application-framework](https://github.com/UW-Madison-DoIT/uw-frame): Optional supplemental user interface enhancing [Apereo uPortal](https://www.apereo.org/projects/uportal). * [massive.js](https://github.com/dmfay/massive-js): A data access library for Node and PostgreSQL. * [electron](https://github.com/electron/electron): Build cross-platform desktop apps with JavaScript, HTML, and CSS. * [scroll-utility](https://github.com/LeDDGroup/scroll-utility): A simple to use scroll utility package for centering elements, and smooth animations * [Blaze UI](https://github.com/BlazeUI/blaze): Framework-free open source UI toolkit. * [Monica](https://github.com/monicahq/monica): An open source personal relationship management system. * [mhy](https://mhy.js.org): A zero-config, out-of-the-box, multi-purpose toolbox and development environment. * [@tandil/diffparse](https://github.com/danielduarte/diffparse#readme): Simple parser for Diff files (unified diff format). * [@tandil/diffsplit](https://github.com/danielduarte/diffsplit#readme): Easy split of .diff & .patch into its files. * [@thi.ng/umbrella](https://github.com/thi-ng/umbrella): Broadly scoped ecosystem & monorepo of ~185 TypeScript projects for general purpose, functional, data driven development * [yii2-basic-firestarter](https://github.com/HunWalk/yii2-basic-firestarter): 🔥 An enhanced Yii2 app template. * [dcyou/resume](https://github.com/dcyou/resume): 😎 Template to easily and quickly create your online CV. * [Nintex Forms](https://www.nintex.com/workflow-automation/modern-forms/): Easily create dynamic online forms to capture and submit accurate and current data. * [Tina CMS](https://tinacms.org): An open source toolkit for building front-end content-management into your website. * [Belajarpython](https://github.com/belajarpythoncom/belajarpython.com) Open source Indonesian python programming tutorial site. * [Uno Platform](https://platform.uno): Build Mobile, Desktop and WebAssembly apps with C# and XAML. Today. Open source and professionally supported. * [Jenkins X](https://jenkins-x.io/): Jenkins X provides pipeline automation, built-in GitOps, and preview environments to help teams collaborate and accelerate their software delivery at any scale. * [GearLock](https://github.com/axonasif/gearlock): Custom Recovery Replacement for Android-x86. * [Changeloguru](https://github.com/haunt98/changeloguru): Auto-generate changelog from conventional commits, written in Go. * [freeCodeCamp](https://www.freecodecamp.org): A nonprofit community that helps you learn to code by building projects. [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) _want your project on this list?_ [send a pull request](https://github.com/conventional-changelog/conventionalcommits.org/pulls). ================================================ FILE: content/next/index.md ================================================ --- draft: true --- # Conventional Commits 1.0.0-next ## Summary The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](http://semver.org), by describing the features, fixes, and breaking changes made in commit messages. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in Semantic Versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in Semantic Versioning). 1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) when the version >= 1.0.0, and [`MINOR`](https://semver.org/#spec-item-4) when on a pre-release 0.y.z version, in Semantic Versioning). A BREAKING CHANGE can be part of commits of any _type_. 1. **INITIAL STABLE RELEASE:** a commit that has a footer `INITIAL STABLE RELEASE:`, or appends `!!` after the type/scope, and introduces a new `MAJOR` even on versions `< 1.0.0`, denoting the promotion from a pre-release version `0.y.z` to `1.0.0`. 1. _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. 1. _footers_ other than `BREAKING CHANGE: ` or `INITIAL STABLE RELEASE: ` may be provided and follow a convention similar to [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Additional types are not mandated by the conventional commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE, or mark an INITIAL STABLE RELEASE).

A scope may be provided to a commit's type, to provide additional contextual information and is contained within parentheses, e.g., `feat(parser): add ability to parse arrays`. ## Examples ### Commit message with description and breaking change footer ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit message with `!` to draw attention to breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### Commit message with scope and `!` to draw attention to breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit message with both `!` and BREAKING CHANGE footer ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit message with `!!` to mark graduating to Production Version 1.0.0 ``` feat!!: send an email to the customer when a product is shipped ``` ### Commit message with `!!` and INITIAL STABLE RELEASE footer ``` feat!!: send an email to the customer when a product is shipped INITIAL STABLE RELEASE: the API is now ready for use by the general public ``` ### Commit message with description and INITIAL STABLE RELEASE footer ``` feat: send an email to the customer when a product is shipped INITIAL STABLE RELEASE: the API is now ready for use by the general public ``` ### Commit message with no body ``` docs: correct spelling of CHANGELOG ``` ### Commit message with scope ``` feat(lang): add polish language ``` ### Commit message with multi-paragraph body and multiple footers ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by the OPTIONAL scope, OPTIONAL `!`, OPTIONAL second `!`, and REQUIRED terminal colon and space. 1. The type `feat` MUST be used when a commit adds a new feature to your application or library. 1. The type `fix` MUST be used when a commit represents a bug fix for your application. 1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parentheses, e.g., `fix(parser):` 1. A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string_. 1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. 1. A commit body is free-form and MAY consist of any number of newline separated paragraphs. 1. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a `:` or `#` separator, followed by a string value (this is inspired by the [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE` and `INITIAL STABLE RELEASE`, which MAY also be used as a token. 1. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed. 1. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer. 1. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., _BREAKING CHANGE: environment variables now take precedence over config files_. 1. If included in the type/scope prefix, breaking changes MUST be indicated by a `!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change. 1. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: updated ref docs._ 1. The units of information that make up conventional commits MUST NOT be treated as case-sensitive by implementors, with the exception of BREAKING CHANGE and INITIAL STABLE RELEASE which MUST be uppercase. 1. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer. 1. Graduating a pre-release 0.y.z version to 1.0.0 MUST be signaled by at least one of: 1. Including `!!` in the type/scope prefix immediately before the `:` 1. Providing `INITIAL STABLE RELEASE:` in the footer section. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've already released the product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### Are the types in the commit title uppercase or lowercase? Any casing may be used, but it's best to be consistent. ### What do I do if the commit contains changes of more than one type? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the conventional commit specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the conventional commit specification? No! If you use a squash based workflow on Git, lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ### How does Conventional Commits handle revert commits? Reverting code can be complicated: are you reverting multiple commits? if you revert a feature, should the next release instead be a patch? Conventional Commits does not make an explicit effort to define revert behavior. Instead we leave it to tooling authors to use the flexibility of _types_ and _footers_ to develop their logic for handling reverts. One recommendation is to use the `revert` type, and a footer that references the commit SHAs that are being reverted: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ### What writing form should I use? We recommend writing a commit description and body using the [imperative](https://en.wikipedia.org/wiki/Imperative_mood) present tense writing form. There are a significant number of examples of this writing form for commits [1](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)[2](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#subject)[3](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project)[4](https://medium.com/@danielfeelfine/commit-verbs-101-why-i-like-to-use-this-and-why-you-should-also-like-it-d3ed2689ef70)[5](https://chris.beams.io/posts/git-commit/) ## About The Conventional Commit specification is inspired by, and based heavily on, the [Angular Commit Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). The first draft of this specification has been written in collaboration with some of the folks contributing to: * [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog): a set of tools for parsing conventional commit messages from git histories. * [bumped](https://bumped.github.io): a tool for releasing software that makes it easy to perform actions before and after releasing a new version of your software. * [unleash](https://github.com/netflix/unleash): a tool for automating the software release and publishing lifecycle. * [lerna](https://github.com/lerna/lerna): a tool for managing monorepos, which grew out of the Babel project. ## Tooling for Conventional Commits * [go-conventionalcommits](https://github.com/leodido/go-conventionalcommits): Full Go powers to parse conventional commits * [go-conventional-commit](https://gitlab.com/digitalxero/go-conventional-commit): go library for parsing commit messages following the specification. * [chglog](https://github.com/goreleaser/chglog): a tool for parsing Conventional Commits messages from git histories and turning them into templateable change logs. * [fastlane-plugin](https://github.com/xotahal/fastlane-plugin-semantic_release): follows the specification to manage versions and generate a changelog automatically. * [php-commitizen](https://github.com/damianopetrungaro/php-commitizen): a tool built to create commit messages following the Conventional Commit specs. Configurable and usable for PHP projects as a composer dependency or usable globally for non-PHP projects. * [php-conventional-changelog](https://github.com/marcocesarato/php-conventional-changelog): a tool built to generate a changelog from a project's committing history messages and metadata and automate versioning with Semver, following Conventional Commits specs. Configurable and usable for PHP projects as a composer dependency or usable globally for non-PHP projects. * [conform](https://github.com/autonomy/conform): a tool that can be used to enforce policies on git repositories, including conventional commits. * [standard-version](https://github.com/conventional-changelog/standard-version): Automatic versioning and CHANGELOG management, using GitHub's new squash button and the recommended Conventional Commits workflow. * [Git Commit Template](https://plugins.jetbrains.com/plugin/9861-git-commit-template): Add _Conventional Commits_ support to [JetBrains Editors](https://www.jetbrains.com/) (IntelliJ IDEA, PyCharm, PhpStorm...). * [commitsar](https://github.com/commitsar-app/commitsar): Go tool for checking if commits on branch are conventional commit compliant. Comes with Docker image for CI uses. * [semantic-release](https://github.com/semantic-release/semantic-release): A tool that automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package. * [ngx-semantic-version](https://github.com/d-koppenhagen/ngx-semantic-version): Automate your Angular app commit- and release-workflow by integrating _commitizen_, _commitlint_, _husky_ and _standard-version_ in your project and configuring it for using _Conventional Commits_. * [Pyhist](https://github.com/jgoodman8/pyhist): A Python utility to automagically update the package version from the git history and generate the Changelog. * [commitizen-tools/commitizen](https://github.com/commitizen-tools/commitizen): A Python tool built to create committing rules for projects (default: conventional commit), bump project versions, and generate changelog. Configurable and usable for both Python and non-Python project. It's highly extensible through Python. * [git-mkver](https://github.com/idc101/git-mkver): A tool to automatically apply Semantic Versioning to git repositories based on _Conventional Commits_. * [Conventional Commits Next Version](https://gitlab.com/DeveloperC/conventional_commits_next_version): A tooling and language agnostic utility to calculate the next semantic version based on the _Conventional Commits_ since the prior version. Supports monorepos. * [change](https://github.com/adamtabrams/change): A tool for generating and updating a changelog using Conventional Commits. * [sv4git](https://github.com/bvieira/sv4git): A command line tool (CLI) to validate commit messages, bump versions, create tags and generate changelogs. * [semantic-gitlog](https://github.com/semantic-gitlog) A simple Semantic Versioning management tool based on Conventional Commits. It automatically derives and manage version numbers and generate angular-style changelogs. supports [Maven](https://github.com/semantic-gitlog/maven-semantic-gitlog) and [Gradle](https://github.com/semantic-gitlog/gradle-semantic-gitlog). * [idea-conventional-commit](https://github.com/lppedd/idea-conventional-commit) Context and template-based completion for conventional/semantic commits. * [Versio](https://github.com/chaaz/versio): A monorepo-compatible tool that updates version numbers based on conventional commits and project dependencies. It can generate tags and changelogs, too. * [Git Changelog Lib](https://github.com/tomasbjerre/git-changelog-lib): A Java library that supports rendering a changelog given a context derived from Git. Supports conventional commits with [Handlebars Helpers](https://github.com/tomasbjerre/git-changelog-lib#helpers). It is used in: * [Gradle](https://github.com/tomasbjerre/git-changelog-gradle-plugin) * [Maven](https://github.com/tomasbjerre/git-changelog-maven-plugin) * [Jenkins](https://github.com/jenkinsci/git-changelog-plugin) * [Command Line](https://github.com/tomasbjerre/git-changelog-command-line) * [Docker](https://hub.docker.com/r/tomasbjerre/git-changelog-command-line) * [GitHub Action](https://github.com/tomasbjerre/git-changelog-github-release) * [Cocogitto](https://github.com/oknozor/cocogitto): Cocogitto is a set of cli tools for the conventional commits and semver specifications. * [Conventional Commits Linter](https://gitlab.com/DeveloperC/conventional_commits_linter): A tooling and language agnostic Git commit linter for the _Conventional Commits_ specification. * [Uplift](https://github.com/gembaadvantage/uplift): Semantic versioning the easy way. Powered by Conventional Commits. Built for use with CI ## Projects Using Conventional Commits * [NFPM](https://github.com/goreleaser/nfpm): NFPM is Not FPM - a simple deb, rpm and apk packager written in Go * [yargs](https://github.com/yargs/yargs): everyone's favorite pirate themed command line argument parser. * [istanbuljs](https://github.com/istanbuljs/istanbuljs): a collection of open-source tools and libraries for adding test coverage to your JavaScript tests. * [uPortal-home](https://github.com/UW-Madison-DoIT/angularjs-portal) and [uPortal-application-framework](https://github.com/UW-Madison-DoIT/uw-frame): Optional supplemental user interface enhancing [Apereo uPortal](https://www.apereo.org/projects/uportal). * [massive.js](https://github.com/dmfay/massive-js): A data access library for Node and PostgreSQL. * [electron](https://github.com/electron/electron): Build cross-platform desktop apps with JavaScript, HTML, and CSS. * [scroll-utility](https://github.com/LeDDGroup/scroll-utility): A simple to use scroll utility package for centering elements, and smooth animations. * [Blaze UI](https://github.com/BlazeUI/blaze): Framework-free open source UI toolkit. * [Monica](https://github.com/monicahq/monica): An open source personal relationship management system. * [mhy](https://mhy.js.org): 🧩 A zero-config, out-of-the-box, multi-purpose toolbox and development environment. * [@tandil/diffparse](https://github.com/danielduarte/diffparse#readme): Simple parser for Diff files (unified diff format). * [@tandil/diffsplit](https://github.com/danielduarte/diffsplit#readme): Easy split of .diff & .patch into its files. * [@thi.ng/umbrella](https://github.com/thi-ng/umbrella): Monorepo of ~100 TypeScript projects for data driven development. * [yii2-basic-firestarter](https://github.com/HunWalk/yii2-basic-firestarter): 🔥 An enhanced Yii2 app template. * [Nintex Forms](https://www.nintex.com/workflow-automation/modern-forms/): Easily create dynamic online forms to capture and submit accurate and current data. * [Tina CMS](https://tinacms.org): An open source toolkit for building front-end content-management into your website. * [Uno Platform](https://platform.uno): Build Mobile, Desktop and WebAssembly apps with C# and XAML. Today. Open source and professionally supported. * [AutoSort.NetCore](https://www.nuget.org/packages/AutoSort.NetCore/): Use entity attributes for default sorting. * [Undercut](https://github.com/the-spyke/undercut): JavaScript lazy data processing pipelines and utilities. * [Stats Builder](https://github.com/MarkFChavez/blox_piece_stats_builder): A stats builder for [Blox Fruits](https://www.roblox.com/games/2753915549/UPDATE-11-Blox-Fruits) * [Jenkins X](https://jenkins-x.io/): Jenkins X provides pipeline automation, built-in GitOps, and preview environments to help teams collaborate and accelerate their software delivery at any scale. * [GearLock](https://github.com/axonasif/gearlock): Custom Recovery Replacement for Android-x86. * [rsql-querydsl](https://github.com/ymind/rsql-querydsl): Integration RSQL query language and Querydsl framework. * [Changeloguru](https://github.com/haunt98/changeloguru): Auto-generate changelog from conventional commits, written in Go. [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) _want your project on this list?_ [send a pull request](https://github.com/conventional-changelog/conventionalcommits.org/pulls). ================================================ FILE: content/v1.0.0/index.ar.md ================================================ --- draft: false aliases: ["/ar/"] --- # Conventional Commits 1.0.0 ## الملخص مواصفة Conventional Commits هي اتفاقية خفيفة الوزن تتعلق برسائل الالتزام (commit messages). توفر مجموعة سهلة من القواعد لإنشاء تاريخ التزام واضح؛ مما يسهل كتابة أدوات آلية تستند إليها. تتوافق هذه الاتفاقية مع [SemVer](http://semver.org)، بوصف الميزات، الإصلاحات، والتغييرات الجوهرية التي تتم في رسائل الالتزام. يجب أن تكون رسالة الالتزام على النحو التالي: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
تحتوي رسالة الالتزام على العناصر الهيكلية التالية، للتواصل مع مستخدمي مكتبتك: 1. **fix:** الالتزام من نوع `fix` يقوم بإصلاح خطأ في قاعدة الكود (يتوافق مع [`PATCH`](http://semver.org/#summary) في الإصدار الدلالي). 2. **feat:** الالتزام من نوع `feat` يقدم ميزة جديدة إلى قاعدة الكود (يتوافق مع [`MINOR`](http://semver.org/#summary) في الإصدار الدلالي). 3. **BREAKING CHANGE:** الالتزام الذي يحتوي على footer `BREAKING CHANGE:` أو إضافة `!` بعد النوع/النطاق، يُدخل تغييراً كبيراً على API (يتوافق مع [`MAJOR`](http://semver.org/#summary) في الإصدار الدلالي). يمكن أن يكون التغيير الجذري جزءًا من أي نوع من الالتزامات. 4. الأنواع الأخرى غير `fix:` و `feat:` مسموحة، مثل [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (استنادًا إلى [اتفاقية Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) التي توصي بـ `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` وغيرها. 5. يُمكن إضافة footers أخرى غير `BREAKING CHANGE: ` والتي تتبع اتفاقية مشابهة لـ [صيغة trail git](https://git-scm.com/docs/git-interpret-trailers). الأنواع الإضافية ليست مفروضة من قبل مواصفة Conventional Commits، وليس لها تأثير ضمني في الإصدار الدلالي (إلا إذا تضمنت تغييرًا جذريًا).

يمكن توفير نطاق (scope) لنوع الالتزام، لتوفير معلومات سياقية إضافية ويكون محصورًا بين قوسين، مثل `feat(parser): add ability to parse arrays`. ## أمثلة ### رسالة التزام مع وصف و footer لتغيير جذري ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### رسالة التزام تحتوي على `!` للفت الانتباه إلى التغيير الجذري ``` feat!: send an email to the customer when a product is shipped ``` ### رسالة التزام تحتوي على نطاق و `!` للفت الانتباه إلى التغيير الجذري ``` feat(api)!: send an email to the customer when a product is shipped ``` ### رسالة التزام تحتوي على `!` و footer لتغيير جذري ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### رسالة التزام بدون body ``` docs: correct spelling of CHANGELOG ``` ### رسالة التزام تحتوي على نطاق ``` feat(lang): add Polish language ``` ### رسالة التزام تحتوي على body متعدد الفقرات و footers متعددة ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## المواصفات الكلمات الرئيسية "MUST"، "MUST NOT"، "REQUIRED"، "SHALL"، "SHALL NOT"، "SHOULD"، "SHOULD NOT"، "RECOMMENDED"، "MAY"، و "OPTIONAL" في هذا المستند يجب تفسيرها كما هو موضح في [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. يجب أن تسبق الالتزامات بنوع، يتكون من اسم مثل `feat`، `fix`، وما إلى ذلك، متبوعًا بـ scope اختياري، و `!` اختياري، والنقطتين الإلزاميتين والمسافة. 2. يجب استخدام النوع `feat` عندما يضيف الالتزام ميزة جديدة لتطبيقك أو مكتبتك. 3. يجب استخدام النوع `fix` عندما يمثل الالتزام إصلاحًا لخطأ في تطبيقك. 4. يمكن توفير scope بعد النوع. يجب أن يتكون scope من اسم يصف جزءًا من قاعدة الكود محاطًا بأقواس، مثل `fix(parser):`. 5. يجب أن يتبع الوصف مباشرة النقطتين والمسافة بعد النوع/النطاق. الوصف هو ملخص قصير للتغييرات في الكود، مثل _fix: array parsing issue when multiple spaces were contained in string_. 6. يمكن توفير body أطول بعد الوصف القصير، لتوفير معلومات سياقية إضافية حول تغييرات الكود. يجب أن يبدأ body بسطر فارغ بعد الوصف. 7. يمكن أن يتكون body من أي عدد من الفقرات مفصولة بأسطر جديدة. 8. يمكن توفير واحد أو أكثر من footers بعد سطر فارغ بعد body. يجب أن يتكون كل footer من رمز (token) متبوعًا إما بـ `:` أو `#` متبوعًا بقيمة نصية (مستوحى من [اتفاقية trailer الخاصة بـ git](https://git-scm.com/docs/git-interpret-trailers)). 9. يجب أن يستخدم token الخاص بـ footer `-` بدلاً من أحرف المسافات، مثل `Acked-by` (يساعد هذا في التفريق بين قسم footers و body متعدد الفقرات). يتم استثناء `BREAKING CHANGE`، الذي يمكن أيضًا استخدامه كـ token. 10. قد تحتوي قيمة footer على مسافات وأسطر جديدة، ويجب أن يتوقف التحليل عندما يتم ملاحظة زوج جديد من token/الفاصل الصحيح. 11. يجب الإشارة إلى التغييرات الجذرية في بادئة النوع/النطاق للالتزام، أو كمدخل في footer. 12. إذا تم تضمينها كـ footer، يجب أن تتكون التغييرات الجذرية من النص بأحرف كبيرة BREAKING CHANGE، متبوعًا بنقطتين ومسافة ووصف، مثل _BREAKING CHANGE: environment variables now take precedence over config files_. 13. إذا تم تضمينها في بادئة النوع/النطاق، يجب الإشارة إلى التغييرات الجذرية بواسطة `!` مباشرة قبل `:`. إذا تم استخدام `!`، يمكن حذف `BREAKING CHANGE:` من قسم footer، ويجب استخدام وصف الالتزام لوصف التغيير الجذري. 14. يمكن استخدام أنواع أخرى غير `feat` و `fix` في رسائل الالتزام، مثل _docs: update ref docs_. 15. لا يجب التعامل مع وحدات المعلومات التي تتكون منها Conventional Commits على أنها حساسة لحالة الأحرف من قبل المنفذين، باستثناء BREAKING CHANGE الذي يجب أن يكون بأحرف كبيرة. 16. يجب أن تكون BREAKING-CHANGE مرادفة لـ BREAKING CHANGE عند استخدامها كـ token في footer. ## لماذا نستخدم Conventional Commits؟ * إنشاء CHANGELOGs تلقائيًا. * تحديد رفع الإصدار الدلالي تلقائيًا (استنادًا إلى أنواع الالتزامات المضافة). * التواصل بطبيعة التغييرات إلى الزملاء والجمهور وغيرهم من أصحاب المصلحة. * تشغيل عمليات البناء والنشر. * تسهيل مساهمة الأشخاص في مشاريعك من خلال السماح لهم باستكشاف تاريخ الالتزامات بشكل منظم. ## الأسئلة المتكررة ### كيف أتعامل مع رسائل الالتزام في مرحلة التطوير الأولية؟ نوصي بأن تتعامل كما لو أنك أصدرت المنتج بالفعل. عادةً ما يكون هناك *شخص ما*، حتى لو كانوا مطورين آخرين، يستخدمون البرنامج. سيرغبون في معرفة ما الذي تم إصلاحه وما هي التغييرات الكبيرة. ### هل تكون الأنواع في عنوان الالتزام بأحرف كبيرة أو صغيرة؟ يمكن استخدام أي حالة، ولكن من الأفضل أن تكون متسقة. ### ماذا أفعل إذا كان الالتزام يتوافق مع أكثر من نوع من الأنواع؟ يفضل أن تقوم بعمل عدة التزامات كلما كان ذلك ممكنًا. جزء من فائدة Conventional Commits هو دفعنا لإجراء التزامات وتنظيم أكثر. ### ألا يشجع ذلك على الحد من سرعة التطوير والتكرار السريع؟ إنه يشجع على عدم التحرك بسرعة بطريقة غير منظمة. يساعدك على التحرك بسرعة على المدى الطويل عبر مشاريع متعددة مع مساهمين متنوعين. ### هل قد تؤدي "Conventional Commits" إلى تقييد المطورين في نوع الـ commits التي يقومون بها لأنهم سيفكرون في الأنواع المقدمة؟ تشجع "Conventional Commits" المطورين على القيام بمزيد من أنواع الـ commits مثل الإصلاحات (fixes). بخلاف ذلك، فإن مرونة "Conventional Commits" تسمح لفريقك بتحديد أنواعهم الخاصة وتغيير تلك الأنواع مع مرور الوقت. ### كيف يرتبط هذا بـ SemVer؟ يجب أن تترجم الـ commits من النوع `fix` إلى إصدارات `PATCH`. ويجب أن تترجم الـ commits من النوع `feat` إلى إصدارات `MINOR`. الـ commits التي تحتوي على `BREAKING CHANGE`، بغض النظر عن النوع، يجب أن تترجم إلى إصدارات `MAJOR`. ### كيف يجب أن أقوم بتحديد الإصدارات لامتداداتي لمواصفة "Conventional Commits"، مثل `@jameswomack/conventional-commit-spec`؟ نوصي باستخدام SemVer لإصدار امتداداتك الخاصة لهذه المواصفة (ونشجعك على تطوير هذه الامتدادات!). ### ماذا أفعل إذا استخدمت نوع commit خاطئ عن طريق الخطأ؟ #### عندما تستخدم نوعاً موجوداً في المواصفة ولكنه ليس النوع الصحيح، مثل `fix` بدلاً من `feat` قبل الدمج أو إصدار الخطأ، نوصي باستخدام `git rebase -i` لتعديل تاريخ الـ commits. بعد الإصدار، تختلف عملية التصحيح اعتماداً على الأدوات والعمليات التي تستخدمها. #### عندما تستخدم نوع commit غير موجود في المواصفة، مثل `feet` بدلاً من `feat` في أسوأ الأحوال، إذا تم تمرير commit لا يتوافق مع مواصفة "Conventional Commits"، فليس هذا نهاية العالم. هذا يعني ببساطة أن هذا الـ commit لن يتم التعرف عليه بواسطة الأدوات التي تعتمد على هذه المواصفة. ### هل يحتاج جميع المساهمين في مشروعي إلى استخدام مواصفة "Conventional Commits"؟ لا! إذا كنت تستخدم أسلوب "squash" في Git، يمكن للمسؤولين الرئيسيين تنظيف رسائل الـ commits عند الدمج، دون إضافة عبء على المساهمين العرضيين. إحدى الأساليب الشائعة لذلك هي أن يقوم نظام git تلقائيًا بـ "squash" الـ commits من طلب السحب (pull request) ويعرض نموذجًا للمسؤول الرئيسي لإدخال رسالة git commit المناسبة للدمج. ### كيف تتعامل "Conventional Commits" مع الـ commits الخاصة بالتراجع (revert)؟ يمكن أن يكون التراجع عن الشيفرة معقداً: هل تقوم بالتراجع عن عدة commits؟ إذا كنت تتراجع عن ميزة (feature)، هل يجب أن يكون الإصدار التالي تصحيحاً (patch) بدلاً من ذلك؟ لا تبذل "Conventional Commits" جهداً صريحاً لتحديد سلوك التراجع. بدلاً من ذلك، نترك الأمر لمطوري الأدوات للاستفادة من مرونة الأنواع والتذييلات (_types_ و _footers_) لتطوير منطقهم في التعامل مع التراجعات. أحد التوصيات هو استخدام نوع `revert`، وتذييل يشير إلى SHAs الخاصة بالـ commits التي يتم التراجع عنها: ``` revert: لن نتحدث أبداً عن حادثة الـ noodle مرة أخرى Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.be.md ================================================ --- draft: false aliases: ["/be/"] --- # Пагадненне аб камітах 1.0.0 ## Сціслы агляд Спецыфікацыя па дадаванню лёгкачытэльных паведамленняў у камітах для людзей і робатаў. Яно апісвае просты набор правілаў для стварэння зразумелай гісторыі камітаў, а таксама дазваляе прасцей распрацоўваць прылады аўтаматызацыі, заснаваныя на гісторыі камітаў. Дадзенае пагадненне сумяшчальна з [Семантычным Версіянаваннем](https://semver.org/), апісваючы новыя функцыі, выпраўленні і змяненні, парушаючыя адваротную сумяшчальнасць паведамленняў камітаў. Паведамленні камітаў павінны быць наступнай структуры: --- ``` <тып>[неабавязковы кантэкст]: <апісанне> [неабавязковае цела] [неабавязковая(ыя) зноска(і)] ``` ---
Каміт змяшчае наступныя структурныя элементы для перадачы намераў карыстыльнікаў вашай бібліятэкі: 1. **fix:** каміт _тыпу_ `fix` выпраўляе баг у вашам кодзе (адпавядае [`PATCH`](https://semver.org/#summary) у Семантычным Версіянаванні). 1. **feat:** каміт _тыпу_ `feat` дадае новую функцыю ў ваш код (адпавядае [`MINOR`](https://semver.org/#summary) у Семантычным Версіянаванні). 1. **BREAKING CHANGE:** каміт, які мае _зноску_ `BREAKING CHANGE` або каміт, які скончваецца клічнікам (`!`) пасля _тыпу_ ці _кантэксту_, уводзячы змяненне(і), парушаючыя адваротную сумяшчальнасць (адпавядае [`MAJOR`](https://semver.org/#summary) у Семантычным Версіянаванні). `BREAKING CHANGE` можа быць часткай каміту любога _тыпу_. 1. Іншыя _тыпы_ камітаў дазволены. Напрыклад, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (заснаваны на [пагадненні Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рэкамендуе `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test` і іншыя. 1. Іншыя _зноскі_ камітаў могуць быць аналягічны паведамленню [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Дадатковыя _тыпы_ не патрабуюцца «Пагадненню аб камітах» і ня маюць невідавочнага эфекту ў семантычным версіянаванні (калі толькі яны не ўключаюць `BREAKING CHANGE`).

_Кантэкст_ можа быць дададзены да _тыпу_ каміту, каб даць дадатковую кантэкстную інфармацыю; яна трываецца ў дужках. Напрыклад, `feat(parser): add ability to parse arrays`. ## Прыклады ### Паведамленне каміту з _апісаннем_ і _зноскай_ `BREAKING CHANGE` ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Паведамленне каміту з `!` для звяртання ўвагі на `BREAKING CHANGE` ``` feat!: send an email to the customer when a product is shipped ``` ### Паведамленне каміту з _кантэкстам_ і `!` для звяртання ўвагі на `BREAKING CHANGE` ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Паведамленне каміту разам з `!` і _зноскай_ `BREAKING CHANGE` ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Паведамленне каміту бяз _цела_ ``` docs: correct spelling of CHANGELOG ``` ### Паведамленне каміту з _кантэкстам_ ``` feat(lang): add polish language ``` ### Паведамленне каміту с _целам_ з некалькіх абзацаў і некалькімі _зноскамі_ ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Поўная Спецыфікацыя Словы «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» у дадзенам дакуменце павінна тлумачыцца як у [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Каміты павінны (MUST) пачынацца з _тыпу_, які з'яўляецца назоўнікам: `feat`, `fix` і г.д. За ім ідзе неабавязковы (OPTIONAL) _кантэкст_, неабавязковы (OPTIONAL) клічнік (`!`) і абавязковае (REQUIRED) двукроп'е (`:`) і прабел (` `). 1. _Тып_ `feat` павінны (MUST) выкарыстоўвацца, калі каміт дадае новы функцыянал у ваша прыкладанне або вашу бібліятэку. 1. _Тып_ `fix` павінны (MUST) выкарыстоўвацца, калі каміт выпраўляе баг у вашам прыкладанні ці ў вашай бібліятэцы. 1. _Кантэкст_ можа (MAY) ісці пасля _тыпу_. _Кантэкст_ павінны (MUST) быць назоўнікам, заключаным у круглыя дужкі, апісваючы частку кодавай базы, якую закрануў каміт. Напрыклад, `fix(parser)`. 1. _Апісанне_ павінна (MUST) ісці адразу пасля двукроп'я (`:`) і з прабелам (` `) пасля _тыпу_ або _кантэксту_. _Апісанне_ ўяўляе сабой сціслае выкладанне змен коду. Напрыклад, `fix: array parsing issue when multiple spaces were contained in string`. 1. _Цела_ каміту можа (MAY) ісці пасля сціслага _апісання_, дадаючы дадатковую кантэкстную інфармацыю пра змены ў кодзе. _Цела_ павінна (MUST) аддзяляцца ад _апісання_ адным пустым радком. 1. _Цела_ каміту мае самавольную форму и можа (MAY) складацца з любой колькасці абзацаў, падзеленых новым радком. 1. У адной ці некалькіх _зносках_ можа (MAY) быць адзін пусты радок пасля _цела_. Кожная _зноска_ павінна (MUST) складацца з токена слову, за якім ідзе раздзяляльнік `:<прабел>` ці `<прабел>#`, за якім ідзе радковае значэнне (заснавана на [git trailer format](https://git-scm.com/docs/git-interpret-trailers)). 1. Токен _зноскі_ павінны (MUST) карыстаць `-` замест прабельных сымбаляў. Напрыклад, `Acked-by` (гэта дапамагае адрозніць раздзел _зноскі_ ад яго _цела_, складаючагася з некалькіх абзацаў). Выключэнне складае `BREAKING CHANGE`, якое можа (MAY) таксама выкарыстоўвацца як токен. 1. _Зноска_ можа (MAY) змяшчаць прабелы і сымбалі новага радку, а счытванне павінна (MUST) завяршацца пры выяўленні наступнай дапушчальнай пары токен-раздзяляльнік _зноскі_. 1. Крытычныя змяненні павінны (MUST) быць указаны ў _тыпу_, _кантэксту_ або _зносцы_ каміту. 1. Калі `BREAKING CHANGE` уключана ў _зноску_, то яно павінна (MUST) спалучацца з вялікіх літар ў тэксце `BREAKING CHANGE`, за якім ідзе двукроп'е (`:`), прабел (` `) і _апісанне_. Напрыклад, `BREAKING CHANGE: environment variables now take precedence over config files`. 1. Калі крытычныя змяненні знаходзяцца ў _тыпу_ або _кантэксту_, то яны павінны (MUST) быць пазначаны клічнікам (`!`), непасрэдна перад двукроп'ем (`:`). Калі выкарыстоўваецца клічнік (`!`), то `BREAKING CHANGE` можа (MAY) быць апушчаны ў _зносцы_, а _апісанне_ каміту павінна (SHALL) выкарыстоўвацца для апісання крытычнага змянення. 1. У вашых паведамленнях камітаў могуць (MAY) выкарыстоўвацца _тыпы_, адменныя ад `feat` і `fix`. Напрыклад, `docs: updated ref docs`. 1. Адзінкі інфармацыі, якія складаюць «Пагадненне аб камітах», не павінны (MUST NOT) апрацоўвацца распрацоўнікамі як адчувальныя да рэгістру, за выключэннем `BREAKING CHANGE`, каторае павінна (MUST) пісацца вялікімі літарамі. 1. `BREAKING-CHANGE` павінны (MUST) быць сінонімам `BREAKING CHANGE` пры выкарыстоўванні ў якасці токена ў _зносцы_. ## Навошта выкарыстоўваць «Пагадненне аб камітах» * Аўтаматычнае стварэнне спісаў змяненняў. * Аўтаматычнае вызначэнне семантычнага павышэння версіі (на падставе _тыпаў_ здзейсненых камітаў). * Інфармаванне сябраў па камандзе, супольнасці і іншых зацікаўленых старон аб характары змяненняў. * Запуск працэсаў зборкі і публікацыі. * Спрасціце людзям удзел у вашых праектах, дазволіўшы ім вывучаць больш структураваную гісторыі камітаў. ## FAQ (часта задаваныя пытанні) ### Як мне абысціся з паведамленнямі камітаў на пачатковым этапе распрацоўкі? Мы раім дзейнічаць так, быццам бы вы ўжо выпусцілі прадукт. Звычайна *хтосьці*, нават калі то вашыя калегі-распрацоўнікі праграмнага забеспячэння, карыстаецца вашым праграмным забеспячэннем. Яны пажадаюць ведаць, што выпраўлена, што ламаецца і г.д. ### _Тыпы_ ў загалоўку каміту павінны пісацца вялікімі ці маленікімі літарамі? Выбярыце той, які вам больш падабаецца, і строга яго прытрымлівайцеся. ### Што мне рабіць, калі каміт адпавядае больш чым аднаму _тыпу_? Па магчымасці вярніцеся назад і зрабіце некалькі камітаў. Часткай перавагі «Пагаднення аб камітах» з'яўляецца здольнасць заахвочваць нас рабіць больш арганізаваныя каміты і PRs (pull requests, ці запыты на запросы на выцягванне). ### Хіба то не перашкаджае інтэнсіўнай распрацоўцы і хуткай ітэрацыі? Гэта перашкаджае хуткаму неарганізаванаму руху. Гэта дапаможа вам хутка прасоўвацца ў доўгатэрміновай перспектыве ў некалькіх праектах з рознымі ўдзельнікамі. ### Ці можа «Пагадненне аб камітах» прывесці распрацоўнікаў да абмежавання _тыпаў_ здзейсненых імі камітаў, таму што яны будуць думаць у адпаведнасці з дазволенымі _тыпамі_? «Пагадненне аб камітах» схіляе нас рабіць больш вызначаных _тыпаў_ камітаў, такіх, як `fix`. Акрамя гэтага, гібкасць «Пагаднення аб камітах» дазваляе вашай камандзе прыдумваць свае асабістыя _тыпы_ і з цягам часу змяняць іх. ### Як гэта звязана з Семантычным Версіянаваннем? Каміты _тыпу_ `fix` павінны быць пераведзены ў выпускі `PATCH`, `feat` — у `MINOR`, `BREAKING CHANGE`, незалежна ад _тыпу_, — у `MAJOR`. ### Як мне давесці свае расшырэнні да спецыфікацыі «Пагадненне аб камітах». Напрыклад, `@jameswomack/standard-commit-spec`? Мы раім выкарыстоўваць Семантычнае Версіянаванне для выпуску вашых уласных расшырэнняў для гэтай спецыфікацыі (і заклікаем вас ствараць гэтыя расшырэнні!). ### Што мне рабіць, калі я выпадкова скарыстаў няправільны _тып_ каміту? #### Калі вы скарысталі няправільны _тып_, але адпаведны спецыфікацыі. Напрыклад, `fix` замест `feat` Перад аб'яднаннем або выпускам памылкі мы раім выкарыстоўваць `git rebase -i` для рэдагавання гісторыі камітаў. Пасля выпуску рэдагаванне будзе адрознівацца ў залежнасці ад таго, якія прылады і працэсы вы выкарыстоўваеце. #### Калі вы скарысталі _тып_, не прызначаны у спецыфікацыі. Напрыклад, `feet` замест `feat` У горшым выпадку гэта ўсё яшчэ не канец свету, калі каміт не адпавядае спецыфікацыі «Пагаднення аб камітах». Гэта проста азначае, што каміт будзе прапушчаны прыладамі, заснаванымі на спецыфікацыі. ### Ці ўсе мае ўдзельнікі павінны карыстацца спецыфікацыяй «Пагаднення аб камітах»? Не! Калі вы выкарыстоўваеце рабочы працэс на падставе з'яднання (squash) камітаў у Git, то вядучыя спецыялісты па суправаджэнню могуць прывесці ў парадак паведамленні камітаў па меры іх зліцця (merge), не дадаючы нагрузкі для звычайных камітараў. Звычайны рабочы працэс для гэтага і заключаецца ў тым, каб ваша сістэма Git аўтаматычна з'яднала каміты з PR і прывяла форму для вядучага суправаджаючага, каб увесці найбольш падыходзячае паведамленне для зліцця. ### Як «Пагадненне аб камітах» апрацоўвае скасаванне камітаў? Скасаванне змяненняў коду можа быць складаным: - Вы скасоўваеце змяненні некалькіх камітаў? - Калі вы скасоўваеце змяненні новых функцый, ці павінны наступны выпуск быць патчам? «Пагадненне аб камітах» ня робіць яўных спробаў вызначыць паводзіны скасавання змен. Замест гэтага мы пакідаем аўтарам прылад выкарыстоўваць гібкасць _тыпаў_ і _зносак_ для распрацоўкі сваёй лёгікі і для апрацоўкі скасавання змен. Адна з парад — выкарыстоўваць _тып_ `revert` і _зноску_, якая спасылаецца на касаваныя хэш-сумы камітаў. Напрыклад: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.bn.md ================================================ --- draft: false aliases: ["/bn/"] --- # প্রচলিত কমিটসমূহ ১.০.০ Conventional Commits 1.0.0 > Commit এর বাংলা অর্থ দাঁড়ায় **'সমর্পণ করা'** বা **'সোপর্দ করা'**, কিন্তু আমরা এখানে **"কমিট"** শব্দটিই ব্যবহার করবো। গিট বা অন্যান্য সফটওয়্যার ডেভেলপমেন্ট প্ল্যাটফর্মে কমিট হলো এমন একটি প্রক্রিয়া যার মাধ্যমে নতুন পরিবর্তনগুলি সংরক্ষণ করা হয়। ## সারসংক্ষেপ **প্রচলিত কমিটসমূহের নির্দিষ্টকরণ (রীতি)** হলো কমিট বার্তার (commit messages) উপরে একটি সহজতর প্রচলন। এটি একটি সুস্পষ্ট কমিট ইতিহাস (commit history) তৈরি করার জন্য নিয়ম-কানুনের একটি সহজ সেট প্রদান করে; যার উপর (কমিট ইতিহাসের) ভিত্তি করে পরবর্তিতে স্বয়ংক্রিয় সরঞ্জাম (tools) লেখা/তৈরি করা সহজ হয়। এই প্রচলণটি কমিট বার্তাগুলিতে করা বৈশিষ্ট্য, সংশোধন এবং উল্লেখযোগ্য পরিবর্তনগুলির বর্ণনার ধরণ দিয়ে [SemVer (Sementic Versioning)](http://semver.org)-এর সাথে সমন্বিত। কমিট বার্তার ক্ষেত্রে নিম্নরূপ গঠন অনুসরণ করা উচিতঃ --- বাংলায়ঃ ``` <ধরণ>[ঐচ্ছিক প্রসার]: <বিবরণ/কমিট শিরোনাম> [ঐচ্ছিক বিস্তারিত তথ্য] [ঐচ্ছিক উপসংহার/পরিশেষ] ``` ইংরেজিতেঃ ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
আপনার প্রকল্পের সাথে সম্পর্কিতদের কাছে নতুন কাজ বা পরিবর্তনের অভিপ্রায় জানাতে কমিট-এ নিম্নলিখিত কাঠামোগত উপাদান থাকবেঃ 1. **fix:** ফিক্স মানে সংশোধন। _ধরণ (type)_ `fix` প্রকৃতির একটি কমিট আপনার কোডবেসে একটি ত্রুটি সংশোধন করা বোঝায় (এটি শব্দার্থিক সংস্করণে (Semantic Versioning) [`PATCH`](http://semver.org/#summary)-এর সাথে সম্পর্কযুক্ত)। 1. **feat:** এটি feature-এর সংক্ষিপ্ত রূপ, এর মানে বৈশিষ্ট্য। _ধরণ (type)_ `feat`-এর একটি কমিট আপনার কোডবেসে একটি নতুন বৈশিষ্ট্য প্রবর্তন করা বোঝায় (এটি শব্দার্থিক সংস্করণে [`MINOR`](http://semver.org/#summary)-এর সাথে সম্পর্কযুক্ত)। 1. **BREAKING CHANGE:** একটি কমিট যার পরিশেষে (footer) `BREAKING CHANGE:` রয়েছে, অথবা ধরণ/প্রসার (type/scope) পরে একটি `!` যুক্ত রয়েছে, তার দ্বারা উল্লেখযোগ্য হারে কোড বা API পরিবর্তন করা হয়েছে বোঝায় (এটি শব্দার্থিক সংস্করণে [`MAJOR`](http://semver.org/#summary)-এর সাথে সম্পর্কিত)। একটি BREAKING CHANGE যেকোনো কমিট _ধরণ (type)_-এর অংশ হতে পারে। 1. `fix:` এবং `feat:` ছাড়া অন্যান্য _ধরণ_ বা _types_ অনুমোদিত, যেমন [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional ) ([Angular প্রচলণ](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) এর উপর ভিত্তি করে) আপনাকে `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, এবং অন্যান্য ধরণ ব্যবহারে উৎসাহিত করে। 1. [গিট ট্রেলার ফর্ম্যাট](https://git-scm.com/docs/git-interpret-trailers) এর অনুরূপ প্রচলন অনুসরণ করে `BREAKING CHANGE: ` (`উল্লেখ্যযোগ্য পরিবর্তন: <বিবরণ>`) ছাড়াও অন্য _পরিশেষ_ বা _footers_ প্রদান করা যেতে পারে। অতিরিক্ত ধরণসমূহ (types) প্রচলিত কমিটসমূহের নির্দিষ্টকরণ (রীতি) দ্বারা বাধ্যতামূলক নয়, এবং শব্দার্থিক সংস্করণে এর কোন অন্তর্নিহিত প্রভাব নেই (যদি না তা একটি উল্লেখযোগ্য পরিবির্তন (BREAKING CHANGE) অন্তর্ভুক্ত করে)।

অতিরিক্ত প্রাসঙ্গিক তথ্য প্রদানের জন্য একটি কমিটের ধরণ/প্রকার (type) -এর পাশে একটি প্রসার তথ্য (scope) প্রদান করা যেতে পারে এবং তা `()` বন্ধনীর মধ্যে থাকে। গঠন হবে এরকম -> `ধরণ(প্রসার): কমিট শিরোনাম..`। উদাহরণঃ `feat(parser): add ability to parse arrays`; এর দ্বারা বোঝানো হচ্ছে কোডবেসের 'parser' অংশে বৈশিষ্ট হিসেবে অ্যারে পার্স করার সক্ষমতা যোগ করা হয়েছে। ## উদাহরণ ### বিবরণ এবং উল্লেখযোগ্য পরিবর্তন (BREAKING CHANGE) পরিশেষ (footer) সহ কমিট বার্তা ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### উল্লেখযোগ্য পরিবর্তনের (BREAKING CHANGE) প্রতি দৃষ্টি আকর্ষণ করতে `!` দিয়ে কমিট বার্তা ``` feat!: send an email to the customer when a product is shipped ``` ### উল্লেখযোগ্য পরিবর্তনের (BREAKING CHANGE) প্রতি দৃষ্টি আকর্ষণ করতে প্রসার (scope) এবং `!` সহ কমিট বার্তা ``` feat(api)!: send an email to the customer when a product is shipped ``` ### পরিশেষে (footer) উল্লেখযোগ্য পরিবর্তন (BREAKING CHANGE) এবং `!` , উভয় সহ কমিট বার্তা ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### বিস্তারিত তথ্য (body) ছাড়াই কমিট বার্তা ``` docs: correct spelling of CHANGELOG ``` ### প্রসার (scope) সহ কমিট বার্তা ``` feat(lang): add Bangla language ``` ### বিস্তারিত তথ্য (body) সমৃদ্ধ একাধিক-অনুচ্ছেদ এবং একাধিক পরিশেষ (footers) সহ কমিট বার্তা ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## নির্দিষ্টকরণ এই নথিতে বর্ণিত "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", এবং "OPTIONAL" মূল শব্দগুলি [RFC ২১১৯](https://www.ietf.org/rfc/rfc2119.txt) অনুসারে অর্থ প্রকাশ করে। 1. কমিটসমূহ MUST (অবশ্যই) একটি ধরণের (type) উপসর্গ (prefix) দিয়ে শুরু করতে হবে, যার মধ্যে একটি বিশেষ্য (noun), `feat`, `fix`, ইত্যাদি থাকবে, এরপর OPTIONAL (ঐচ্ছিক) প্রসার (scope), OPTIONAL (ঐচ্ছিক) `!`, এবং প্রয়োজনীয় টার্মিনাল কোলন (`:`) এবং স্পেস REQUIRED (থাকতে হবে)। 1. `feat` ধরণটি MUST (অবশ্যই) ব্যবহার করতে হবে যখন কোনো কমিট আপনার অ্যাপ্লিকেশন বা লাইব্রেরিতে একটি নতুন বৈশিষ্ট্য (feature) যুক্ত করে। 1. `fix` ধরণটি MUST (অবশ্যই) ব্যবহার করতে হবে যখন কোনো কমিট আপনার অ্যাপ্লিকেশনে একটি ত্রুটি সংশোধন (fix) করে। 1. ধরণের (type) এর সাথে একটি প্রসার (scope) প্রদান করা (MAY) যেতে পারে। একটি প্রসার (scope) MUST (অবশ্যই) একটি বিশেষ্য (noun) নিয়ে গঠিত হবে যা কোডবেসের একটি অংশকে ইঙ্গিত করবে এবং `()` বন্ধনী দ্বারা বেষ্টিত থাকবে। উদাহরণস্বরূপ, কোডবেসের parser অংশে একটি সংশোধনমূলক কমিট করতে আমরা ব্যবহার করবো `fix(parser):`। 1. ধরণ/প্রসার (type/scope) উপসর্গ (prefix) এর সাথে কোলন এবং স্পেস (`: `) এর পরপরই MUST (অবশ্যই) একটি বিবরন (description) থাকতে হবে। বিবরণটি কোডে পরিবর্তনের সংক্ষিপ্ত সারাংশ হবে। গঠণঃ `<ধরণ/(প্রসার)>: <বিবরণ>`। উদাহরণস্বরূপ, `fix: array parsing issue when multiple spaces were contained in string.` 1. সংক্ষিপ্ত বিবরণের (description) পরে একটি কমিটে দীর্ঘ বিস্তারিত তথ্য (body) প্রদান করা (MAY) যেতে পারে, যা কোডের পরিবর্তন সম্পর্কে অতিরিক্ত প্রাসঙ্গিক তথ্য প্রদান করে। বিস্তারিত তথ্য (body) অবশ্যই (MUST) বিবরণের পরে একটি ফাঁকা লাইন রেখে শুরু করতে হবে। 1. কমিটে বিস্তারিত তথ্য (body) সীমাবদ্ধ নয় এবং যেকোন সংখ্যক নতুন লাইনে বিভক্ত অনুচ্ছেদ নিয়ে গঠিত (MAY) হতে পারে। 1. বিস্তারিত তথ্য (body) -এর পরে একটি ফাঁকা লাইন রেখে এক বা একাধিক পরিশেষ (footers) থাকতে (MAY) পারে। প্রতিটি পরিশেষে MUST (অবশ্যই) একটি শব্দ টোকেন থাকবে, তারপর একটি `:<স্পেস>` বা `<স্পেস>#` বিভাজক থাকবে, তারপর একটি স্ট্রিং মান থাকবে (এটি [গিট ট্রেলার প্রচলণ](https://git-scm.com/docs/git-interpret-trailers) দ্বারা অনুপ্রাণিত)। 1. একটি পরিশেষের (footer's) টোকেন হিসেবে হোয়াইটস্পেস অক্ষরের জায়গায় MUST (অবশ্যই) `-` ব্যবহার করতে হবে, যেমন, `Acked-by` (এটি বিস্তারিত তথ্য (body) সমৃদ্ধ্ বহু-অনুচ্ছেদ থেকে পরিশেষ বিভাগকে আলাদা করতে সাহায্য করে)। তবে `BREAKING CHANGE`-এর জন্য তা ব্যতিক্রম রাখা হয়েছে, যা টোকেন হিসেবেও ব্যবহার করা (MAY) যেতে পারে। 1. একটি পরিশেষের মানের মধ্যে স্পেস এবং নতুন লাইন থাকতে (MAY) পারে, এবং পরবর্তী যুক্তিসিদ্ধ পরিশেষ (footer) টোকেন/বিভাজক জোড়া পরিলক্ষিত হলে পার্সিং (parsing) MUST (অবশ্যই) বন্ধ করতে হবে। 1. উল্লেখযোগ্য পরিবর্তনগুলি MUST (অবশ্যই) কমিটের প্রকার/প্রসার (type/scope) উপসর্গে (prefix) বা পরিশেষে একটি লিপিভুক্ত (entry) হিসাবে নির্দেশিত হতে হবে। 1. পরিশেষ (footer) হিসেবে অন্তর্ভুক্ত করা হলে, একটি উল্লেখযোগ্য পরিবর্তন (breaking change) এর মধ্যে MUST (অবশ্যই) বড় হাতে লেখা 'BREAKING CHANGE' থাকতে হবে, তারপর যথাক্রমে একটি কোলন, স্পেস এবং বিবরণ। যেমন, `BREAKING CHANGE: environment variables now take precedence over config files`। 1. প্রকার/প্রসার (type/scope) উপসর্গ (prefix) অন্তর্ভুক্ত থাকলে, উল্লেখযোগ্য পরিবর্তনসমূহ নির্দেশ করার জন্য `:` এর ঠিক আগে MUST (অবশ্যই) একটি `!` ব্যবহার করতে হবে। যদি `!` ব্যবহার করা হয়, তবে পরিশেষ (footer) বিভাগ থেকে `BREAKING CHANGE:` বাদ দেওয়া যেতে (MAY) পারে এবং উল্লেখযোগ্য পরিবর্তন বর্ণনা করতে কমিট বিবরণ (description) ব্যবহার (SHALL) করা হবে। 1. `feat` এবং `fix` ছাড়াও অন্যান্য ধরণ আপনার কমিট বার্তাগুলিতে ব্যবহার করা (MAY) যেতে পারে, যেমন, `docs: update ref docs.`। 1. তথ্যের একক যা প্রচলিত কমিটসমূহ (Conventional Commits) তৈরি করে তা বাস্তবায়নকারীদের দ্বারা কোন ভাবেই কেস সংবেদনশীল (case sensitive) হিসাবে ব্যবহার (MUST NOT) করা যাবে না, তবে 'BREAKING CHANGE' এর ক্ষেত্রে ব্যতিক্রম যা MUST (অবশ্যই) বড় হাতের হতে হবে। 1. পরিশেষে টোকেন হিসেবে ব্যবহৃত হলে 'BREAKING-CHANGE' অবশ্যই (MUST) 'BREAKING CHANGE'-এর সমার্থক হতে হবে। ## কেন প্রচলিত কমিটসমূহের (নির্দিষ্টকরণ রীতি) ব্যবহার করবেন * স্বয়ংক্রিয়ভাবে পরিবর্তনধারা (CHANGELOG) তৈরি করতে। * স্বয়ংক্রিয়ভাবে শব্দার্থিক (semantic) সংস্করণ নির্ধারণ বা পরিবর্তন করতে (কমিটসমূহের ধরণের উপর ভিত্তি করে)। * পরিবর্তনের প্রকৃতি সহকর্মী, জনসাধারণ এবং অন্যান্য অংশীদারদের মধ্যে যথাযথ ভাবে প্রকাশ করতে। * প্রস্তুত (build) এবং প্রকাশ (publish) প্রক্রিয়া চালু করতে। * একটি অধিকতর কাঠামোবদ্ধ কমিট ইতিহাস অন্বেষণ করার মধ্য দিয়ে আপনার প্রকল্পে অন্য মানুষদেরকে অবদান রাখাকে সহজ করতে। ## সচরাচর জিজ্ঞাসিত প্রশ্নাবলি > বৈষয়িক সুবিধার জন্য প্রশ্নাবলির বাংলা শিরোনামের নিচে ইংরেজি প্রশ্নও রাখা হয়েছে। (এক্ষেত্রে আক্ষরিক অর্থ উপেক্ষিত) ### প্রাথমিক উন্নয়ন (development) পর্যায়ে আমি কীভাবে কমিট বার্তাগুলির ব্যবস্থা নিবো? How should I deal with commit messages in the initial development phase? আমরা সুপারিশ করি যে আপনি এমনভাবে এগিয়ে যান যেন আপনি ইতিমধ্যে পণ্যটি প্রকাশ (release) করে ফেলেছেন। সাধারণত *কেউ*, এমনকি আপনার সহকর্মীরা যদি আপনার সফ্টওয়্যার ব্যবহার করেন, তারা জানতে চাইবেন কি সমাধান হয়েছে, কিসে সমস্যা আছে ইত্যাদি। ### কমিট শিরোনামের (লিখার) ধরণ কি বড় হাতের বা ছোট হাতের? Are the types in the commit title uppercase or lowercase? যেকোন ধরণ (case) ব্যবহার করা যেতে পারে, তবে প্রকল্প জুড়ে সামঞ্জস্য বজায় রাখা ভালো। ### কমিট যদি একাধিক কমিট ধরনের (types) সাথে সঙ্গতিপূর্ণ হয় তাহলে আমি কী করব? What do I do if the commit conforms to more than one of the commit types? সম্ভব হলে পিছনে যান এবং একাধিক কমিট করুন। Conventional Commits বা প্রচলিত কমিটসমূহের (নির্দিষ্টকরণ রীতির) উপকারের অংশ বা সক্ষমতা হলো এটি আমাদেরকে আরও সংগঠিত কমিট এবং পুল অনুরোধ (PR) করতে উৎসাহিত করে। ### এটা কি দ্রুত উন্নয়ন এবং দ্রুত পুনরাবৃত্তিকে নিরুৎসাহিত করে না? Doesn’t this discourage rapid development and fast iteration? এটি আপনাকে দীর্ঘমেয়াদে একাধিক প্রকল্প জুড়ে বিভিন্ন অবদানকারীদের সাথে নিয়ে দ্রুত অগ্রসর হতে সাহায্য করে, কিন্তু অসংগঠিত উপায়ে দ্রুত অগ্রসর হতে নিরুৎসাহিত করে। ### প্রচলিত কমিটসমূহ (Conventional Commits) কি ডেভেলপারদের জন্য কমিটের ধরন সীমাবদ্ধ করতে পারে যেহেতু তারা প্রদত্ত ধরনগুলি নিয়েই চিন্তা করবে? Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits বা প্রচলিত কমিটসমূহ (নির্দিষ্টকরণ রীতি) আমাদেরকে নির্দিষ্ট ধরনের আরও অধিক কমিট ব্যবহার করতে উৎসাহিত করে। তাছাড়াও, প্রচলিত কমিটসমূহের নমনীয়তা আপনার দলকে তাদের নিজস্ব ধরণ (types) ব্যবহার করতে এবং সময়ের সাথে সাথে সেই ধরণ বা প্রকারগুলিকে পরিবর্তন করার অনুমতি দেয়৷ ### এটি কিভাবে সেমভারের (SemVer) সাথে সম্পর্কিত? How does this relate to SemVer? `fix` কমিট ধরণকে `PATCH` হিসেবে অনুবাদ করা যায়। `feat` ধরনের কমিটকে `MINOR` হিসেবে অনুবাদ করা যায়। কমিটসমূহে `BREAKING CHANGE` কমিটকে, ধরণ (type) নির্বিশেষে, `MAJOR` হিসেবে অনুবাদ করা যায়। ### আমি কীভাবে আমার এক্সটেনশনগুলিকে প্রচলিত কমিটসমূহের নির্দিষ্টকরণ রীতিতে সংস্করণ করব, যেমন `@forhadakhan/conventional-commit-spec`? How should I version my extensions to the Conventional Commits Specification, e.g. `@forhadakhan/conventional-commit-spec`? আমরা এই নির্দিষ্টকরণ রীতিতে আপনার নিজস্ব এক্সটেনশন প্রকাশ করতে [SemVer](http://semver.org/#summary) ব্যবহার করার পরামর্শ দিচ্ছি (এবং এই এক্সটেনশনগুলি তৈরি করতে আপনাকে উত্সাহিত করছি!) ### আমি ভুলবশত যদি ভুল কমিট ধরণ ব্যবহার করে ফেলি তাহলে কি করব? What do I do if I accidentally use the wrong commit type? #### যখন আপনি রীতির মধ্যে থাকা একটি ধরন (type) ব্যবহার করেন কিন্তু তা সঠিক ধরন (type) নয়, উদাহরণস্বরূপ `feat` এর পরিবর্তে `fix` ব্যবহার। ভুল কমিট একত্রিত (merge) বা প্রকাশ (release) করার আগে, `git rebase -i` ব্যবহার করে কমিট ইতিহাস সম্পাদনা বা পরিবর্তন করতে পারেন। প্রকাশিত (released) হয়ে গেলে, আপনি কোন টুল এবং প্রক্রিয়া ব্যবহার করেছেন তা অনুযায়ী সংশোধন প্রক্রিয়া ভিন্ন হবে। #### যখন আপনি রীতির বাইরে কোনো ধরন (type) ব্যবহার করেন, উদাহরণস্বরূপ `feat` এর পরিবর্তে `feet` ব্যবহার। সবচেয়ে খারাপ পরিস্থিতিতে, যদি একটি কমিট 'প্রচলিত কমিটসমূহের নির্দিষ্টকরণ রীতি'-এর শর্ত পূরণ না করে তবে এখানেই যে দুনিয়া শেষ, বিষয়টি এমন নয়। কেবলমাত্র ঐ প্রকল্পে 'প্রচলিত কমিটসমূহের নির্দিষ্টকরণ রীতি'-এর উপর ভিত্তি করে কোন স্বয়ংক্রিয় প্রক্রিয়া ব্যবহৃত হলে, তাতে ভুলকৃত কমিট-টি চিহ্নিত হবে না। ### আমার সমস্ত অবদানকারীদের কি প্রচলিত কমিটসমূহের নির্দিষ্টকরণ রীতি ব্যবহার করতে হবে? Do all my contributors need to use the Conventional Commits specification? না! যদি আপনি গিটের স্কোয়াশ ভিত্তিক কর্মপ্রবাহ (squash-based workflow) ব্যবহার করেন, তবে প্রধান রক্ষকরা একত্রিত (merge) হওয়ার সময় কমিট বার্তাগুলিকে পরিষ্কার করতে পারেন — এটি সাধারণ অবদানকারী বা কমিটকারীদের-কে কাজের কোনো চাপ দেয় না। এর জন্য একটি প্রচলিত কর্মপ্রবাহ হল আপনার গিট সিস্টেমে স্বয়ংক্রিয়ভাবে পুল (pull) অনুরোধ থেকে কমিটগুলি স্কোয়াশ করা এবং প্রধান রক্ষণাবেক্ষণকারীকে মার্জ করার সময় যথাযথ গিট কমিট বার্তা প্রবেশ করার জন্য একটি ফর্ম উপস্থাপন করা। ### কিভাবে প্রচলিত কমিটসমূহ প্রত্যাবর্তন কমিট পরিচালনা করে? How does Conventional Commits handle revert commits? > রিভার্ট বা প্রত্যাবর্তন মানে পূর্বের কোন অবস্থায় ফেরত যাওয়া। কোড প্রত্যাবর্তন (revert) করা জটিল হতে পারে: আপনি কি একাধিক কমিট প্রত্যাবর্তন করছেন? যদি আপনি একটি বৈশিষ্ট্য প্রত্যাবর্তন করেন, তাহলে কি পরবর্তী প্রকাশ (release) একটি পূর্ণ প্রকাশ বা উন্মোচন-এর পরিবর্তে একটি patch (সহজ কথায় 'জোড়া/তালি') হওয়া উচিত? প্রচলিত কমিটসমূহ (Conventional Commits) প্রত্যাবর্তন আচরণকে সংজ্ঞায়িত করার জন্য কোনো সুস্পষ্ট নীতি প্রয়োগের প্রচেষ্টা করে না। বরং _types_ এবং _footers_-এর নমনীয়তা ব্যবহার করে প্রত্যাবর্তন পরিচালনার জন্য যুক্তির বিকাশ করতে এটিকে লেখকদের (coders) উপর ছেড়ে দেয়। তবে একটি সুপারিশ হলো ধরণ (type) হিসেবে `revert` ব্যবহার করা এবং যে কমিটকে প্রত্যাবর্তন করা হচ্ছে তার SHA-কে উল্লেখ করে একটি পরিশেষ (footer) ব্যবহার করা। যেমনঃ ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.de.md ================================================ --- draft: false aliases: ["/de/"] --- # Konventionelle Commits 1.0.0 ## Zusammenfassung Die Spezifikation für konventionelle Commits ist eine einfache Konvention, die auf Commit-Nachrichten aufbaut. Sie enthält einfache Regeln zum Erstellen einer expliziten Commit-Historie; das macht es einfacher, automatisierte Tools dazu zu schreiben. Diese Konvention knüpft an [SemVer](http://semver.org/lang/de/) an, indem sie die Funktionen, Korrekturen und Änderungen beschreibt, die in Commit-Nachrichten vorgenommen wurden. Die Commit-Nachricht sollte wie folgt aufgebaut sein: --- ``` [optionaler Gültigkeitsbereich]: [optionaler Textkörper] [optionale Fußnoten] ``` ---
Der Commit enthält die folgenden Strukturelemente, um den Benutzern Ihrer Bibliothek Ihre Absichten mitzuteilen: 1. **fix:** ein Commit des _Typs_ `fix` behebt einen Fehler in Ihrer Codebasis (dies entsprich einem [`PATCH`](http://semver.org/#summary) in semantischer Versionierung). 1. **feat:** ein Commit des _Typs_ `feat` führt eine neue Funktion in Ihrer Codebasis ein (dies entspricht einem [`MINOR`](http://semver.org/#summary) in semantischer Versionierung). 1. **BREAKING CHANGE:** ein Commit mit `BREAKING CHANGE:` in der Fußzeile, oder einem angehängten `!` nach dem Typ/Gültigkeitsbereich, führt tiefgreifende Änderungen an der API ein (dies entspricht einem [`MAJOR`](http://semver.org/#summary) in semantischer Versionierung). Ein BREAKING CHANGE kann Teil eines Commits jeden _Typs_ sein. 1. Andere _Typen_ als `fix:` und `feat:` sind erlaubt, z. B. erlaubt [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (basierend auf [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, und andere. 1. Andere _Fußzeilen_ als `BREAKING CHANGE: ` können angegeben werden und folgen der Konvention ähnlich zum [git Trailer Format](https://git-scm.com/docs/git-interpret-trailers). Zusätzliche Typen sind in der konventionellen Commit-Spezifikation nicht vorgeschrieben und haben keine impliziten Auswirkungen auf die semantische Versionierung (sofern sie keinen BREAKING CHANGE enthalten).

Ein Gültigkeitsbereich kann zusammen mit einem Commit Typen angegeben werden, um weitere kontextuelle Informationen in Klammern zu geben, z. B. `feat(parser): add ability to parse arrays`. ## Beispiele ### Commit-Nachricht mit Beschreibung und Breaking Change Fußzeile ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit-Nachricht mit `!` um auf einen Breaking Change aufmerksam zu machen ``` feat!: send an email to the customer when a product is shipped ``` ### Commit-Nachricht mit Gültigkeitsbereich und `!` um auf einen Breaking Change aufmerksam zu machen ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit-Nachricht mit `!` als auch BREAKING CHANGE Fußzeile ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit-Nachricht ohne Textkörper ``` docs: correct spelling of CHANGELOG ``` ### Commit-Nachricht mit Gültigkeitsbereich ``` feat(lang): add polish language ``` ### Commit-Nachricht mit mehreren Absätzen und Fußzeilen ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Spezifikation Die Schlüsselwörter "MUSS", "DARF NICHT", "ERFORDERLICH", "SOLL", "SOLL NICHT", "SOLLTE", "SOLLTE NICHT", "EMPFOHLEN", "KANN" und "OPTIONAL" dieses Dokuments werden wie in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) interpretiert. 1. Commits MÜSSEN einen Typen vorangestellt haben, der aus Nomen besteht, `feat`, `fix`, etc., gefolgt von einem OPTIONALEN Gültigkeitsbereich, OPTIONALEM `!` und einem ERFORDERLICHEN abschließenden Doppelpunkt und einem Leerzeichen. 1. Der Typ `feat` MUSS benutzt werden, wenn ein Commit neue Funktionalität zur Applikation oder Bibliothek hinzufügt. 1. Der Typ `fix` MUSS benutzt werden, wenn ein Commit eine Fehlerbehebung für die Applikation darstellt. 1. Ein Gültigkeitsbereich KANN nach einem Typen angegeben werden. Ein Gültigkeitsbereich MUSS aus einem Nomen in Klammern bestehen, das die betroffene Stelle im Code beschreibt, z. B. `fix(parser):` 1. Eine Beschreibung MUSS direkt auf den Doppelpunkt und ein Leerzeichen nach dem Typ/Gültigkeitsbereich folgen. Die Beschreibung ist eine kurze Zusammenfassung der Code-Änderungen, z. B. _fix: array parsing issue when multiple spaces were contained in string_. 1. Ein längerer Commit-Textkörper KANN nach der Kurzbeschreibung angegeben werden, um weitere kontextuelle Informationen über die Code-Änderungen zu geben. Der Textkörper MUSS nach eine Leerzeile nach der Beschreibung folgen. 1. Der Commit-Textkörper ist formlos und KANN aus einer beliebigen Anzahl an Absätzen bestehen, getrennt mit Zeilenumbrüchen. 1. Eine oder mehrere Fußzeilen KÖNNEN nach einer Leerzeile unter dem Textkörper angegeben werden. Jede Fußzeile MUSS aus einem Symbolwort bestehen, gefolgt von einem `:` oder `#` Trennzeichen und einem String-Wert (basierend auf der [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. Symbolwörter MÜSSEN ein `-` statt eines Leerzeichens verwenden, z. B. `Acked-by` (dies hilft die Fußzeile von einem mehrzeiligen Textkörper zu unterscheiden). Eine Ausnahme bildet `BREAKING CHANGE`, was auch als Symbolwort benutzt werden KANN. 1. Der Wert einer Fußzeile KANN Leerzeichen und Zeilenumbrüche enthalten. Das Parsen MUSS beendet werden, wenn das nächste gültige Paar Fußzeilen-Symbolwort/Trennzeichen erkannt wird. 1. Breaking Changes MÜSSEN mit dem Typen-/Gültigkeitsbereichs-Präfix eines Commits angegeben werden oder als Eintrag in der Fußzeile. 1. Wenn ein Breaking Change als Fußzeile eingefügt wird, MUSS sie aus dem Großbuchstaben BREAKING CHANGE bestehen, gefolgt von einem Doppelpunkt, einem Leerzeichen und einer Beschreibung, z. B. _BREAKING CHANGE: environment variables now take precedence over config files_. 1. Wenn im Typen-/Gültigkeitsbereichs-Präfix enthalten, MÜSSEN Breaking Changes mit einem `!` direkt vor dem `:` angegeben werden. Wenn `!` benutzt wird KANN `BREAKING CHANGE:` aus der Fußzeile weggelassen werden und die Commit-Beschreibung SOLL benutzt werden um den Breaking Change zu beschreiben. 1. Andere Typen als `feat` und `fix` KÖNNEN in der Commit-Nachricht benutzt werden, z. B. _docs: updated ref docs._ 1. Die Informationseinheiten, aus denen herkömmliche Commits bestehen, DÜRFEN von Implementierern NICHT mit Groß- und Kleinschreibung behandelt werden, mit Ausnahme von BREAKING CHANGE, bei dem es sich um Großbuchstaben handeln MUSS. 1. BREAKING-CHANGE MUSS mit BREAKING CHANGE synonym bleiben, wenn es als Symbolwort in der Fußzeile benutzt wird. ## Warum konventionelle Commits? * Automatisch generierende CHANGELOGs. * Automatisches Ermitteln einer semantischen Versionserhöhung (basierend auf den eingestellten Commit-Typen). * Kommunikation der Art von Änderungen an Teamkollegen, die Öffentlichkeit und andere Stakeholder. * Auslösen von Build- und Veröffentlichungsprozessen. * Erleichtern Sie es Leuten, einen Beitrag zu Ihren Projekten zu leisten, indem Sie ihnen ermöglichen, einen strukturierteren Commit-Verlauf zu erkunden. ## FAQ ### Wie soll ich in der ersten Entwicklungsphase mit Commit-Nachrichten umgehen? Wir empfehlen so zu verfahren, als ob Sie das Produkt bereits freigegeben hätten. In der Regel verwendet _jemand_ Ihre Software, auch wenn es sich nur um Ihre Kollegen handelt. Diese werden wissen wollen, was repariert ist, was kaputt geht usw. ### Sind Typen im Commit-Titel in Groß- oder Kleinbuchstaben? Das ist ganz Ihnen überlassen, aber seien Sie dabei konsequent. ### Was mache ich, wenn der Commit mehr als einem der Commit-Typen entspricht? Gehen Sie zurück und führen Sie nach Möglichkeit mehrere Commits durch. Ein Vorteil von konventionellen Commits ist, dass wir besser organisierte Commits und Pull Requests durchführen können. ### Verhindert dies nicht eine rasche Entwicklung und schnelle Iteration? Es verhindert sich auf unorganisierte Weise schnell voranzubewegen. Es hilft Ihnen dabei, sich langfristig und schnell über mehrere Projekte mit unterschiedlichen Mitwirkenden hinweg zu bewegen. ### Könnten konventionelle Commits Entwickler dazu veranlassen, die Art der Commits zu begrenzen, die sie machen, weil sie in den zur Verfügung gestellten Typen denken werden? Konventionelle Commits ermutigen uns, bestimmte Arten von Commits wie z. B. Fixes zu verwenden. Abgesehen davon ermöglicht die Flexibilität der konventionellen Commits Ihrem Team, eigene Typen zu entwickeln und diese Typen im Laufe der Zeit zu ändern. ### In welcher Beziehung steht dies zu SemVer? Commits vom Typ `fix` sollten wie `PATCH` Releases behandelt werden. Commits vom Typ `feat` sollten wie `MINOR` Releases behandelt werden. Commits mit `BREAKING CHANGE` in den Commits sollten unabhängig vom Typ wie `MAJOR` Releases behandelt werden. ### Wie soll ich meine Erweiterungen der konventionellen Commit Spezifikation versionieren, z. B. `@jameswomack/conventional-commit-spec`? Wir empfehlen die Verwendung von SemVer, um Ihre eigenen Erweiterungen für diese Spezifikation zu veröffentlichen (und begrüßen es, diese Erweiterungen vorzunehmen!) ### Was mache ich, wenn ich versehentlich den falschen Commit-Typ verwende? #### Wenn Sie einen Typ verwendet haben, der der Spezifikation, aber nicht dem richtigen Typ entspricht, z. B. `fix` statt `feat` Vor dem Mergen oder Freigeben des Fehlers wird empfohlen, mit `git rebase -i` die Commit Historie zu bearbeiten. Nach der Veröffentlichung ist die Bereinigung je nach den verwendeten Tools und Prozessen unterschiedlich. #### Wenn Sie einen Typ verwendet haben, der *nicht* der Spezifikation entspricht, z. B. `feet` statt `feat` Im schlimmsten Fall ist es nicht das Ende der Welt, wenn ein Commit nicht der konventionellen Commit Spezifikation entspricht. Dies bedeutet lediglich, dass der Commit nicht von Tools erfasst wird, die sich an die Spezifikation halten. ### Müssen alle meine Mitwirkenden die konventionelle Commit Spezifikation verwenden? Nein! Wenn Sie einen Squash-basierten Workflow auf Git benutzen, können Lead Maintainer die Commit-Nachrichten beim Mergen bereinigen — ohne gelegentlichen Committern zusätzliche Arbeit aufzubürden. Ein üblicher Workflow hierfür ist, dass Ihr Git-System automatisch Commits aus einem Pull Request squasht und dem Lead Maintainer ein Formular vorlegt, in dem er die richtige Git-Commit-Nachricht für den Merge eingibt. ### Wie geht Conventional Commits mit Revert Commits um? Das Zurücksetzen von Code kann kompliziert sein: Setzen Sie mehrere Commits zurück? Wenn Sie ein Feature zurücksetzen, sollte die nächste Version stattdessen ein Patch sein? Konventionelle Commits bemühen sich nicht explizit, das Wiederherstellungsverhalten zu definieren. Stattdessen überlassen wir es den Autoren, die Flexibilität von _Typen_ und _Fußzeilen_ zu nutzen, um ihre Logik für die Behandlung von Reverts zu entwickeln. Eine Empfehlung wäre, den `revert` Typ und eine Fußzeile zu verwenden, die auf die zurückgesetzten Commit-SHAs verweist: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.es.md ================================================ --- draft: false aliases: ["/es/"] --- # Commits Convencionales 1.0.0 ## Resumen La especificación de Commits Convencionales es una convención ligera sobre los mensajes de commits. Proporciona un conjunto sencillo de reglas para crear un historial de commits explícito; lo que hace más fácil escribir herramientas automatizadas encima del historial. Esta convención encaja con [SemVer](http://semver.org/lang/es/), al describir en los mensajes de los commits las funcionalidades, arreglos, y cambios de ruptura hechos. El mensaje del commit debe ser estructurado de la siguiente manera: --- ``` [ámbito opcional]: [cuerpo opcional] [nota(s) al pie opcional(es)] ``` ---
El commit contiene los siguientes elementos estructurales, para comunicar la intención a los consumidores de tu librería: 1. **fix:** un commit de _tipo_ `fix` corrige un error en la base del código (se correlaciona con [`PATCH`](http://semver.org/#summary) en el Versionado Semántico). 1. **feat:** un commit de _tipo_ `feat` introduce una nueva funcionalidad en la base del código (se correlaciona con [`MINOR`](http://semver.org/#summary) en el Versionado Semántico). 1. **BREAKING CHANGE:** un commit que contiene la nota al pie `BREAKING CHANGE:`, o que agrega un `!` después del tipo/ámbito, introduce un cambio de ruptura de API (se correlaciona con [`MAJOR`](http://semver.org/#summary) en el Versionado Semántico). Un BREAKING CHANGE puede ser parte de commits de cualquier _tipo_. 1. _tipos_ distintos a `fix:` y `feat:` están permitidos, por ejemplo [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (basados en [la convención de Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) que recomienda `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, y otros. 1. _notas al pie_ distintas de `BREAKING CHANGE: ` pueden ser añadidas y siguen una convención similar al [formato git trailer](https://git-scm.com/docs/git-interpret-trailers). Tipos adicionales no son obligatorios en la especificación de Commits Convencionales, y no tienen un efecto implícito en el Versionado Semántico (al menos que incluyan un BREAKING CHANGE).

Un ámbito puede ser añadido al tipo de un commit, para proveer información adicional contextual y debe ser contenido entre paréntesis, ej., `feat(parser): add ability to parse arrays`. ## Ejemplos ### Mensaje de commit con descripción y cambio de ruptura en la nota al pie ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Mensaje de commit con `!` para llamar la atención al cambio de ruptura ``` refactor!: drop support for Node 6 ``` ### Mensaje de commit con ambos `!` y BREAKING CHANGE en la nota al pie ``` refactor!: drop support for Node 6 BREAKING CHANGE: refactor to use JavaScript features not available in Node 6. ``` ### Mensaje de commit sin cuerpo ``` docs: correct spelling of CHANGELOG ``` ### Mensaje de commit con ámbito ``` feat(lang): added polish language ``` ### Mensaje de commit con cuerpo multi-párrafo y múltiples notas al pie ``` fix: correct minor typos in code see the issue for details on typos fixed. Reviewed-by: Z Refs #133 ``` ## Especificación Las palabras clave “DEBE” (“MUST”), “NO DEBE” (“MUST NOT”), “REQUERIDO” (“REQUIRED”), “DEBERÁ” (“SHALL”), “NO DEBERÁ” (“SHALL NOT”), “DEBERÍA” (“SHOULD”), “NO DEBERÍA” (“SHOULD NOT”), “RECOMIENDA” (“RECOMMENDS”), “PUEDE” (“MAY”) y “OPCIONAL” (“OPTIONAL”) en este documento se deben interpretar como se describe en [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Los commits DEBEN iniciarse con un prefijo de tipo que consiste en un sustantivo, `feat`, `fix`, etc., seguido del ámbito OPCIONAL, `!`OPCIONAL, y dos puntos y un espacio REQUERIDO. 2. El tipo `feat` DEBE ser usado cuando un commit agrega una nueva funcionalidad a la aplicación o librería. 3. El tipo `fix` DEBE ser usado cuando el commit representa una corrección a un error en el código de la aplicación (bug). 4. Un ámbito PUEDE ser añadido después de un tipo. Un ámbito DEBE consistir en un sustantivo que describa una sección de la base del código encerrado entre paréntesis, ej., `fix(parser):`. 5. Una descripción DEBE ir inmediatamente después de los dos puntos y el espacio del prefijo de tipo/ámbito. La descripción es resúmen corto de los cambios realizados en el código, ej., _fix: array parsing issue when multiple spaces were contained in string._. 6. Un cuerpo de commit más extenso PUEDE agregarse después de la descripción corta, dando información contextual adicional acerca de los cambios en el código. El cuerpo DEBE iniciar después de una línea en blanco después de la descripción. 7. Un cuerpo de commit es de forma-libre y PUEDE consistir de cualquier número de párrafos separados por una nueva línea. 8. Una o más notas al pie PUEDEN ser añadidas una línea en blanco después del cuerpo. Cada nota al pie DEBE consistir de una palabra clave, seguida ya sea por un separador `:` o `#`, seguido por un valor cadena (string) (esto está inspirado por la [convención git trailer](https://git-scm.com/docs/git-interpret-trailers)). 9. Una palabra clave de una nota al pie DEBE usar `-` en lugar de caracteres de espacios en blanco, ej., `Acked-by` (esto ayuda a diferenciar la sección de la nota al pie de un cuerpo multi párrafo). Se hace una excepción para `BREAKING CHANGE`, que también PUEDE ser usada como palabra clave. 10. Una nota al pie PUEDE contener espacios y líneas en blanco, y el parseo DEBE terminar cuando se observe el siguiente separador/clave. 11. Los cambios de ruptura DEBEN ser indicados en el prefijo de tipo/ámbito de un commit, o como una entrada en la nota al pie. 12. Si se incluye como una nota al pie, un cambio de ruptura DEBE consistir del texto en mayúsculas BREAKING CHANGE, seguido de dos puntos, y una descripción, ej., _BREAKING CHANGE: environment variables now take precedence over config files_. 13. Si se incluye en el prefijo de tipo/ámbito, cambios de ruptura DEBEN ser indicados por un `!` inmediatamente después de `:`. Si `!` es usado, `BREAKING CHANGE:` PUEDE ser omitido de la sección de la nota al pie, y la descripción del commit DEBERÁ ser usada para describir el cambio de ruptura. 14. Tipos diferentes a `feat` y `fix` PUEDEN ser usados en los mensajes de commit, ej., _docs: updated ref docs._. 15. Las unidades de información que componen Commits Convencionales NO DEBEN ser tratados como implementadores sensitivos de caso, con la excepción de BREAKING CHANGE que DEBE ir en mayúsculas. 16. BREAKING-CHANGE DEBE ser sinónimo de BREAKING CHANGE, cuando se usa en una nota al pie. ## ¿Por qué usar Commits Convencionales? * Generación automática de CHANGELOGs. * Determinación automática de un salto de versión semántico (basado en los tipos de commits utilizados). * Comunicar la naturaleza de los cambios a los demás integrantes del equipo, el público o cualquier otro interesado. * Activar procesos de procesos y publicación. * Hacer más fácil a otras personas contribuir al proyecto al permitirles explorar una historia de los commits más estructurada. ## FAQ (Preguntas Frecuentes) ### ¿Cómo puedo trabajar con los mensajes de los commits en la etapa inicial de desarrollo? Recomendamos trabajar como si ya hubieras lanzado tu producto. Típicamente _alguien_, incluso si son tus compañeros desarrolladores, están usando tu software. Ellos querrán saber qué se ha arreglado, qué se ha dañado, etc. ### ¿Los tipos en los títulos de los commits están en mayúsculas o en minúsculas? Se puede utilizar cualquiera, pero es mejor ser coherente. ### ¿Qué hago si el commit se ajusta a más de uno de los tipos de commit? Regresa y haz múltiples commits de ser posible. Parte de los beneficios de los Commits Convencionales es la habilidad para hacer commits y PRs más organizados. ### ¿No desalienta esto el desarrollo y la iteración rápida? Desalienta moverse rápido de una forma desorganizada. Te ayuda a ser capaz de moverte rápido a largo plazo a través de proyectos con una gran variedad de contribuidores. ### ¿Pueden los Commits Convencionales llevar a los desarrolladores a limitar el tipo de commits que hacen ya que estarán pensando en los tipos previstos? Los Commits Convencionales nos animan a hacer más de ciertos tipos de commits como _fixes_. Adicionalmente, la flexibilidad de los Commits Convencionales le permite a tu equipo generar sus propios tipos y cambiarlos a lo largo del tiempo. ### ¿Cómo se relaciona esto con SemVer? El tipo de commit `fix` se traduce a un cambio de versión `PATCH`. El tipo de commit `feat` se traduce a un cambio de versión `MINOR`. Commits con el texto `BREAKING CHANGE`, sin importar su tipo, se traducen a un cambio de versión `MAJOR`. ### ¿Cómo debo versionar mis extensiones a la especificación de Commits Convencionales, e.g. `@jameswomack/conventional-commit-spec`? Recomendamos usar SemVer para liberar tu propia extensión a esta especificación (¡Y te animamos a hacer esta extensión!) ### ¿Qué debo hacer si por accidente uso un tipo de commit equivocado? #### Cuando utilizaste un tipo que es de la especificación pero del tipo correcto, e.g. `fix` en lugar de `feat` Antes de combinar o liberar el error, recomendamos usar `git rebase -i` para editar el historial de los commits. Después de que se ha liberado, la limpieza será distinta de acuerdo a las herramientas y procesos que hayas utilizado. #### Cuando usas un tipo que no está en la especificación, ej. `feet` en lugar de `feat` En el peor de los escenarios, no es el fin del mundo si aparece un commit que no cumple con las especificaciones de los Commits Convencionales. Simplemente significa que el commit será ignorado por las herramientas que se basen en esta especificación. ### ¿Deben todos los que contribuyen a mi proyecto usar esta especificación? ¡No! Si usas un flujo de trabajo basado en `squash` los líderes del proyecto pueden limpiar el mensaje en el momento en que se incorpora, sin agregar cargas adicionales a quienes contribuyen casualmente. Un flujo de trabajo común para esto es configurar tu sistema de git para que haga el `squash` de manera automática de un pull request y presente al líder del proyecto un formulario para que ingrese el mensaje de commit correcto al momento de hacer el merge. ### ¿Cómo maneja Commits Convencionales el revertir código? Revertir código puede ser complicado: ¿Estás revirtiendo múltiples commits? ¿Si reviertes una funcionalidad, debería ser la siguiente versión un _patch_? Commits Convencionales no hace un esfuerzo explícito para definir el comportamiento al revertir. En lugar de eso le dejamos a los autores de las herramientas la flexibilidad de los _tipos_ y _notas al pie_ para desarrollar la lógica para manejar los _reverts_. Una recomendación es usar el tipo `revert`, y una nota al pie que haga referencia a los commit SHAs que son revertidos: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.fr.md ================================================ --- draft: false aliases: ["/fr/"] --- # Commits Conventionnels 1.0.0 ## Résumé La spécification de Commits Conventionnels est une convention basique pour des messages de commit propres. Elle fournit un ensemble simple de règles pour créer un historique de commit explicite, ce qui facilite l'écriture d'outils automatisés. Cette convention suit [SemVer](http://semver.org/lang/fr/), en décrivant les fonctionnalités, les correctifs et les modifications importantes apportées aux messages de commit. Le message du commit doit être structuré comme suit : --- ``` [étendue optionnelle]: [corps optionnel] [pied optionnel] ``` ---
Le commit contient les éléments structurels suivants, permettant de communiquer à l’intention des consommateurs de votre API : 1. **fix:** un commit de _type_ `fix` corrige un bogue dans le code (cela est en corrélation avec [`PATCH`](http://semver.org/#summary) en gestion sémantique de versions). 1. **feat:** un commit de _type_ `feat` introduit une nouvelle fonctionnalité dans le code (cela est en corrélation avec [`MINOR`](http://semver.org/#summary) en gestion sémantique de versions). 1. **BREAKING CHANGE:** un commit qui contient dans son _pied_ le mot-clé `BREAKING CHANGE:`, ou dont le _type_/_étendue_ est suffixé d'un `!`, introduit une rupture de compatibilité dans l'API (cela est en corrélation avec [`MAJOR`](http://semver.org/#summary) en gestion sémantique de versions). Un BREAKING CHANGE peut faire partie des commits de n'importe quel _type_. 1. Les _types_ autre que `fix:` et `feat:` sont autorisés; par exemple, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (basé sur [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommande `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, etc. 1. Les _pieds_ autres que `BREAKING CHANGE: ` peuvent être fournis et suivre une convention similaire à [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Les types supplémentaires ne sont pas prescrits par la spécification de Commits Conventionnels et n'ont aucun effet implicite dans la gestion des versions sémantiques (à moins qu'ils ne comportent un BREAKING CHANGE).

Une _étendue_ peut être fournie au type d'un commit pour fournir des informations contextuelles supplémentaires. Elle est indiquée entre parenthèses, par exemple, `feat(parser): add the ability to parse arrays`. ## Exemples ### Message du commit avec description et breaking change dans le _pied_ ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Message du commit avec `!` qui attire l'attention sur un BREAKING CHANGE ``` feat!: send an email to the customer when a product is shipped ``` ### Message du commit avec _étendue_ et `!` qui attire l'attention sur un BREAKING CHANGE ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Message du commit avec `!` et BREAKING CHANGE dans le _pied_ ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Message du commit sans _corps_ ``` docs: correct spelling of CHANGELOG ``` ### Message du commit avec _étendue_ ``` feat(lang): add polish language ``` ### Message du commit avec plusieurs paragraphes dans le _corps_, et plusieurs _pieds_ ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Spécification Les mots clés ”DOIT” (“MUST”), “NE DOIT PAS” (“MUST NOT”), “REQUIS” (“REQUIRED”), “DEVRA” (“SHALL”), “NE DEVRA PAS” (“SHALL NOT”), “DEVRAIT” (“SHOULD”), “NE DEVRAIT PAS” (“SHOULD NOT”), “RECOMMANDÉ” (“RECOMMENDED”), “PEUT” (“MAY”), et “FACULTATIF” (“OPTIONAL”) dans ce document doivent être interprétés comme décrit dans [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DOIT être préfixé par un _type_, qui consiste en un nom (`feat`, `fix`, etc.), suivi par une _étendue_ FACULTATIVE, un `!` FACULTATIF, et de deux-points et d'un espace REQUIS. 1. Le type `feat` DOIT être utilisé lorsqu'un commit ajoute une nouvelle fonctionnalité à votre application ou bibliothèque. 1. Le type `fix` DOIT être utilisé lorsqu'un commit représente un correctif pour votre application. 1. Une _étendue_ PEUT être fournie après un _type_. Une _étendue_ DOIT être un nom décrivant une section du code, et être encadrée par des parenthèses, par exemple, `fix(parser):` 1. Une _description_ DOIT suivre immédiatement les deux-points et l'espace après le préfixe _type_/_étendue_. La description est une brève description des modifications du code, par exemple, _fix: array parsing issue when multiple spaces were contained in string_. 1. Un _corps_ de commit PEUT être fourni après la description courte, fournissant des informations contextuelles supplémentaires sur les modifications du code. Le _corps_ DOIT commencer par une ligne vide après la _description_. 1. Un _corps_ est libre et PEUT se composer d'un nombre quelconque de paragraphes séparés par une nouvelle ligne. 1. Un ou plusieurs _pieds_ PEUVENT être fournis avec une ligne blanche après le _corps_. Chaque _pied_ DOIT se composer d'un mot-clé, suivi par `:` ou `#`, suivi d'une chaine de caractère (d'après [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. Un mot-clé de _pied_ DOIT utiliser `-` au lieu des espaces, par exemple, `Acked-by` (cela permet de différencier la section de _pied_ d'un _corps_ de plusieurs paragraphes). Une exception est faite pour `BREAKING CHANGE`, qui PEUT aussi être utilisé comme un mot-clé. 1. La valeur d'un _pied_ PEUT contenir des espaces et des nouvelles lignes, et l'analyse grammaticale DOIT se terminer lorsqu'une nouvelle paire mot-clé / séparateur de _pied_ valide est trouvée. 1. Une _rupture de compatibilité_ DOIT être indiquée soit dans le préfixe _type_/_étendue_ d'un commit, soit comme une entrée dans le _pied_. 1. Si elle est incluse comme _pied_, une _rupture de compatibilité_ DOIT être écrite en majuscules : `BREAKING CHANGE`, suivi par deux-points, espace, et une description, par exemple, _BREAKING CHANGE: environment variables now take precedence over config files_. 1. Si elle est incluse dans le préfixe _type_/_étendue_, une _rupture de compatibilité_ DOIT être indiquée par un `!` immédiatement avant le `:`. Si `!` est utilisé, `BREAKING CHANGE:` PEUT être omis de la section de _pied_, et la _description_ du commit DEVRA être utilisée pour décrire la _rupture de compatibilité_. 1. Un _type_ autre que `feat` et `fix` PEUT être utilisé, par exemple, _docs: updated ref docs._ 1. Les unités d’information qui composent Commits Conventionnels NE DOIVENT PAS être traitées comme sensibles à la casse par les développeurs, à l'exception de BREAKING CHANGE qui DOIT être en majuscules. 1. BREAKING-CHANGE DOIT être synonyme de BREAKING CHANGE, lorsqu'il est utilisé comme mot-clé dans un _pied_. ## Pourquoi utiliser Commits Conventionnels * Générer automatiquement des CHANGELOGs. * Déterminer automatiquement un changement de version sémantique (en fonction des types de commits inclus). * Communiquer la nature des changements aux membres de l'équipe, au public et aux autres parties prenantes. * Déclencher des processus de génération et de publication. * Faciliter la contribution des personnes à vos projets en leur permettant d’explorer un historique de commit plus structuré. ## FAQ ### Comment dois-je gérer les messages de commit dans la phase de développement initiale ? Nous vous recommandons de procéder comme si vous aviez déjà publié un produit. Généralement *quelqu'un*, même si ce sont vos collègues développeurs de logiciels, utilise votre logiciel. Il voudra savoir ce qui est corrigé, ce qui casse, etc. ### Les types dans le titre des commits sont-ils en majuscules ou en minuscules ? N'importe quelle casse (majuscule ou minuscule) peut être utilisée, mais il est préférable d'être cohérent. ### Que dois-je faire si le commit est conforme à plus d'un type de commit ? Revenez en arrière et faites plusieurs commits autant que possible. Une partie des avantages de Commits Conventionnels réside dans sa capacité à nous inciter à créer des commits et des PR plus organisés. ### Est-ce que cela ne décourage pas le développement rapide et l’itération rapide ? Cela décourage les commits rapides et désorganisés. Cela vous aide à être en mesure d'évoluer rapidement et à long terme dans plusieurs projets avec des contributeurs variés. ### Les Commits Conventionnels pourraient-ils amener les développeurs à limiter le type d’engagement qu’ils effectuent car ils réfléchiront aux types fournis ? Les Commits Conventionnels nous encouragent à utiliser davantage certains types de commits, tels que les correctifs. En dehors de cela, la flexibilité des Commits Conventionnels permet à votre équipe de créer ses propres types et de les modifier au fil du temps. ### Quel est le lien avec SemVer ? Les commits de type `fix` doivent être traduits en versions `PATCH`. Les commits de type `feat` doivent être traduits en versions `MINOR`. Les commits avec `BREAKING CHANGE` dans les commits, quel que soit leur _type_, doivent être traduits en versions `MAJOR`. ### Comment dois-je mettre à jour mes extensions de la spécification de Commits Conventionnels, par exemple `@jameswomack/conventionnel-commit-spec` ? Nous vous recommandons d'utiliser SemVer pour publier vos propres extensions à cette spécification (et vous encourageons à les créer !) ### Que dois-je faire si j'utilise accidentellement le type de commit incorrect ? #### Lorsque vous utilisez un type de commit incorrect, par exemple `fix` au lieu de `feat` Avant de fusionner ou de publier l'erreur, nous vous recommandons d'utiliser `git rebase -i` pour éditer l'historique du commit. Après la publication, le nettoyage sera différent selon les outils et les processus que vous utilisez. #### Lorsque vous utilisez un type qui n'est *pas* dans les spécifications, par exemple `feet` au lieu de` feat` Dans le pire des cas, ce n'est pas la fin du monde si un commit atterrit sans respecter les spécifications de Commits Conventionnels. Cela signifie simplement que le commit sera ignoré par des outils basés sur les spécifications. ### Est-ce que tous mes contributeurs doivent utiliser les spécifications de Commits Conventionnels ? Non ! Si vous utilisez un flux de travail Git basé sur `squash`, les responsables principaux peuvent nettoyer les messages de validation au fur et à mesure de leur fusion, ce qui permet de ne pas ajouter de charge de travail aux contributeurs occasionnels. Un processus courant consiste à ce que votre système Git supprime automatiquement les validations d'une demande d'extraction et présente un formulaire permettant au responsable de la maintenance d'entrer le message de validation Git approprié pour la fusion. ### Comment les Commits Conventionnels traitent-ils les annulations de commits ? L'annulation de code peut être compliquée : est-ce une annulation de plusieurs commits ? Si vous annulez une fonctionnalité, la prochaine version devrait-elle être un correctif ? Les Commits Conventionnels ne font pas d'effort explicite pour définir le comportement d'annulation. Au lieu de cela, nous laissons les auteurs d’outils utiliser la flexibilité des _types_ et des _pieds_ pour développer leur logique de traitement des annulations. Une recommandation consiste à utiliser le _type_ `revert` et un _pied_ qui fait référence aux SHA de validation qui sont annulés: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.gr.md ================================================ --- draft: false aliases: ["/gr/"] --- # Conventional Commits 1.0.0 ## Περίληψη Η προδιαγραφή Conventional Commits είναι μια ελαφριά σύμβαση για τα μηνύματα commit. Παρέχει ένα εύκολο σύνολο κανόνων για τη δημιουργία ενός σαφούς ιστορικού των commits, διευκολύνοντας έτσι τη δημιουργία αυτοματοποιημένων εργαλείων. Αυτή η σύμβαση συμβαδίζει με το [SemVer](http://semver.org), περιγράφοντας τα χαρακτηριστικά, τις διορθώσεις και τις αλλαγές που σπάνε τη συμβατότητα (breaking changes) στα μηνύματα των commits. Το μήνυμα commit πρέπει να έχει την ακόλουθη δομή: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
Το commit περιέχει τα ακόλουθα δομικά στοιχεία, για να επικοινωνήσει την πρόθεση στους καταναλωτές της βιβλιοθήκης σας: 1. **fix:** ένα commit τύπου (type) `fix` διορθώνει ένα σφάλμα στον κώδικά σας (αυτό αντιστοιχεί σε `PATCH` στο Semantic Versioning). 1. **feat:** ένα commit τύπου (type) `feat` εισάγει ένα νέο χαρακτηριστικό στον κώδικα (αυτό αντιστοιχεί σε `MINOR` στο Semantic Versioning). 1. **BREAKING CHANGE:** ένα commit που έχει υποσέλιδο (footer) `BREAKING CHANGE:`, ή προσαρτά ένα `!` μετά τον τύπο/scope, εισάγει μια αλλαγή που σπάει τη συμβατότητα του API (breaking change) (αντιστοιχεί σε `MAJOR` στο Semantic Versioning). Μια αλλαγή που σπάει τη συμβατότητα (BREAKING CHANGE) μπορεί να είναι μέρος οποιουδήποτε τύπου commit. 1. **Τύποι (types)** εκτός από `fix:` και `feat:` επιτρέπονται. Για παράδειγμα, το [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (βασισμένο στη [σύμβαση της Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) συνιστά τη χρήση των: `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, και άλλων. 1. **Υποσέλιδα (footers)** εκτός από το `BREAKING CHANGE: ` μπορούν να παρέχονται και να ακολουθούν μια σύμβαση παρόμοια με το [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Η χρήση πρόσθετων τύπων δεν επιβάλλεται από την προδιαγραφή Conventional Commits και δεν επηρεάζει το Semantic Versioning (εκτός αν περιλαμβάνουν μια αλλαγή που σπάει τη συμβατότητα - BREAKING CHANGE).

Ένα scope (πεδίο εφαρμογής) μπορεί να δοθεί στον τύπο ενός commit για να παρέχει πρόσθετες πληροφορίες πλαισίου και περικλείεται σε παρενθέσεις, π.χ., `feat(parser): add ability to parse arrays`. ## Παραδείγματα ### Μήνυμα commit με περιγραφή και υποσέλιδο για breaking change ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Μήνυμα commit με `!` για την επισήμανση μιας breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### Μήνυμα commit με scope και `!` για την επισήμανση μιας breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Μήνυμα commit με `!` και υποσέλιδο BREAKING CHANGE ``` chore!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Μήνυμα commit χωρίς σώμα ``` docs: correct spelling of CHANGELOG ``` ### Μήνυμα commit με scope ``` feat(lang): add Polish language ``` ### Μήνυμα commit με σώμα πολλαπλών παραγράφων και πολλαπλά υποσέλιδα ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Προδιαγραφή Οι λέξεις-κλειδιά "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", και "OPTIONAL" σε αυτό το έγγραφο πρέπει να ερμηνεύονται όπως περιγράφεται στο [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Τα Commits ΠΡΕΠΕΙ να ξεκινούν με ένα πρόθεμα τύπου, το οποίο αποτελείται από ένα ουσιαστικό, `feat`, `fix`, κ.λπ., ακολουθούμενο από το ΠΡΟΑΙΡΕΤΙΚΟ scope (πεδίο εφαρμογής), το ΠΡΟΑΙΡΕΤΙΚΟ `!`, και την ΑΠΑΙΤΟΥΜΕΝΗ άνω και κάτω τελεία και κενό διάστημα. 1. Ο τύπος `feat` ΠΡΕΠΕΙ να χρησιμοποιείται όταν ένα commit προσθέτει ένα νέο χαρακτηριστικό στην εφαρμογή ή τη βιβλιοθήκη σας. 1. Ο τύπος `fix` ΠΡΕΠΕΙ να χρησιμοποιείται όταν ένα commit αντιπροσωπεύει μια διόρθωση σφάλματος για την εφαρμογή σας. 1. Ένα scope ΜΠΟΡΕΙ να δοθεί μετά από έναν τύπο. Ένα scope ΠΡΕΠΕΙ να αποτελείται από ένα ουσιαστικό που περιγράφει ένα τμήμα του κώδικα, περικλειόμενο σε παρενθέσεις, π.χ., `fix(parser):` 1. Μια περιγραφή ΠΡΕΠΕΙ να ακολουθεί αμέσως την άνω και κάτω τελεία και το κενό μετά το πρόθεμα τύπου/scope. Η περιγραφή είναι μια σύντομη περίληψη των αλλαγών του κώδικα, π.χ., _fix: array parsing issue when multiple spaces were contained in string_. 1. Ένα μεγαλύτερο σώμα commit ΜΠΟΡΕΙ να δοθεί μετά τη σύντομη περιγραφή, παρέχοντας πρόσθετες πληροφορίες πλαισίου σχετικά με τις αλλαγές του κώδικα. Το σώμα ΠΡΕΠΕΙ να ξεκινά μία κενή γραμμή μετά την περιγραφή. 1. Ένα σώμα commit είναι ελεύθερης μορφής και ΜΠΟΡΕΙ να αποτελείται από οποιονδήποτε αριθμό παραγράφων που χωρίζονται με νέα γραμμή. 1. Ένα ή περισσότερα υποσέλιδα ΜΠΟΡΕΙ να δοθούν μία κενή γραμμή μετά το σώμα. Κάθε υποσέλιδο ΠΡΕΠΕΙ να αποτελείται από ένα token λέξης-κλειδιού, ακολουθούμενο είτε από ένα διαχωριστικό `:` είτε `#`, ακολουθούμενο από μια τιμή τύπου string (αυτό είναι εμπνευσμένο από τη [σύμβαση git trailer](https://git-scm.com/docs/git-interpret-trailers)). 1. Το token λέξης-κλειδιού ενός υποσέλιδου ΠΡΕΠΕΙ να χρησιμοποιεί `-` αντί για κενά διαστήματα, π.χ., `Acked-by` (αυτό βοηθά στη διαφοροποίηση του τμήματος του υποσέλιδου από ένα σώμα πολλαπλών παραγράφων). Εξαίρεση γίνεται για το `BREAKING CHANGE`, το οποίο ΜΠΟΡΕΙ επίσης να χρησιμοποιηθεί ως token λέξης-κλειδιού. 1. Η τιμή ενός υποσέλιδου ΜΠΟΡΕΙ να περιέχει κενά και νέες γραμμές, και η διαδικασία parsing ΠΡΕΠΕΙ να τερματίζεται όταν εντοπιστεί το επόμενο έγκυρο ζεύγος token λέξης-κλειδιού/διαχωριστικού. 1. Οι αλλαγές που σπάνε τη συμβατότητα (breaking changes) ΠΡΕΠΕΙ να υποδεικνύονται στο πρόθεμα τύπου/scope ενός commit, ή ως εγγραφή στο υποσέλιδο. 1. Εάν περιλαμβάνεται ως υποσέλιδο, μια αλλαγή που σπάει τη συμβατότητα ΠΡΕΠΕΙ να αποτελείται από το κεφαλαίο κείμενο BREAKING CHANGE, ακολουθούμενο από άνω και κάτω τελεία, κενό και περιγραφή, π.χ., _BREAKING CHANGE: οι μεταβλητές περιβάλλοντος έχουν πλέον προτεραιότητα έναντι των αρχείων διαμόρφωσης_. 1. Εάν περιλαμβάνεται στο πρόθεμα τύπου/scope, οι αλλαγές που σπάνε τη συμβατότητα ΠΡΕΠΕΙ να υποδεικνύονται με ένα `!` αμέσως πριν από το `:`. Εάν χρησιμοποιείται το `!`, το `BREAKING CHANGE:` ΜΠΟΡΕΙ να παραλειφθεί από το τμήμα του υποσέλιδου, και η περιγραφή του commit ΠΡΕΠΕΙ να χρησιμοποιείται για την περιγραφή της αλλαγής που σπάει τη συμβατότητα. 1. Τύποι εκτός από `feat` και `fix` ΜΠΟΡΕΙ να χρησιμοποιηθούν στα μηνύματα commit σας, π.χ., _docs: update ref docs._ 1. Για τα στοιχεία που συνθέτουν τα Conventional Commits ΔΕΝ ΠΡΕΠΕΙ να γίνεται διάκριση πεζών-κεφαλαίων από τους υλοποιητές, με εξαίρεση το `BREAKING CHANGE` που ΠΡΕΠΕΙ να είναι με κεφαλαία γράμματα. 1. Το `BREAKING-CHANGE` ΠΡΕΠΕΙ να είναι συνώνυμο με το `BREAKING CHANGE`, όταν χρησιμοποιείται ως token λέξης-κλειδιού σε ένα υποσέλιδο. ## Γιατί να χρησιμοποιήσετε τα Conventional Commits * Αυτόματη δημιουργία CHANGELOGs. * Αυτόματος προσδιορισμός μιας αύξησης της σημασιολογικής έκδοσης (με βάση τους τύπους των commits που έχουν ενσωματωθεί). * Επικοινωνία της φύσης των αλλαγών στους συμπαίκτες, το κοινό και άλλους ενδιαφερόμενους. * Ενεργοποίηση διαδικασιών build και publish. * Διευκόλυνση της συνεισφοράς άλλων στα έργα σας, επιτρέποντάς τους να εξερευνήσουν ένα πιο δομημένο ιστορικό των commits. ## Συχνές Ερωτήσεις ### Πώς πρέπει να χειρίζομαι τα μηνύματα commit στην αρχική φάση ανάπτυξης; Σας συνιστούμε να προχωρήσετε σαν να έχετε ήδη κυκλοφορήσει το προϊόν. Συνήθως *κάποιος*, ακόμα κι αν είναι οι συνάδελφοί σας προγραμματιστές, χρησιμοποιεί το λογισμικό σας. Θα θέλουν να ξέρουν τι έχει διορθωθεί, ποιες αλλαγές σπάνε τη συμβατότητα, κ.λπ. ### Οι τύποι στον τίτλο του commit είναι κεφαλαίοι ή πεζοί; Μπορεί να χρησιμοποιηθεί οποιαδήποτε μορφή (πεζά ή κεφαλαία), αλλά είναι καλύτερο να είστε συνεπείς. ### Τι κάνω αν το commit συμμορφώνεται με περισσότερους από έναν από τους τύπους commit; Προσπαθήστε να δημιουργήσετε πολλαπλά commits όποτε είναι δυνατόν. Μέρος του οφέλους των Conventional Commits είναι η ικανότητά του να μας οδηγεί στο να κάνουμε πιο οργανωμένα commits και PRs. ### Αυτό δεν αποθαρρύνει την ταχεία ανάπτυξη και τη γρήγορη επανάληψη; Αποθαρρύνει το να κινείστε γρήγορα με ανοργάνωτο τρόπο. Σας βοηθά να μπορείτε να κινείστε γρήγορα μακροπρόθεσμα σε πολλαπλά έργα με ποικίλους συνεισφέροντες. ### Μπορεί τα Conventional Commits να οδηγήσουν τους προγραμματιστές να περιορίσουν τον τύπο των commits που κάνουν επειδή θα σκέφτονται με τους παρεχόμενους τύπους; Τα Conventional Commits μας ενθαρρύνουν να κάνουμε περισσότερους από ορισμένους τύπους commits, όπως διορθώσεις. Πέρα από αυτό, η ευελιξία των Conventional Commits επιτρέπει στην ομάδα σας να δημιουργήσει τους δικούς της τύπους και να τους αλλάξει με την πάροδο του χρόνου. ### Πώς σχετίζεται αυτό με το SemVer; Τα commits τύπου `fix` πρέπει να μεταφράζονται σε `PATCH` εκδόσεις. Τα commits τύπου `feat` πρέπει να μεταφράζονται σε `MINOR` εκδόσεις. Τα commits με `BREAKING CHANGE` στα commits, ανεξάρτητα από τον τύπο, πρέπει να μεταφράζονται σε `MAJOR` εκδόσεις. ### Πώς πρέπει να εκδίδω τις επεκτάσεις μου στην Προδιαγραφή Conventional Commits, π.χ. `@jameswomack/conventional-commit-spec`; Συνιστούμε τη χρήση του SemVer για την κυκλοφορία των δικών σας επεκτάσεων σε αυτήν την προδιαγραφή (και σας ενθαρρύνουμε να κάνετε αυτές τις επεκτάσεις!) ### Τι κάνω αν κατά λάθος χρησιμοποιήσω λάθος τύπο commit; #### Όταν χρησιμοποιήσατε έναν τύπο που είναι της προδιαγραφής αλλά όχι ο σωστός τύπος, π.χ. `fix` αντί για `feat` Πριν από τη συγχώνευση ή την κυκλοφορία του λάθους, συνιστούμε τη χρήση του `git rebase -i` για την επεξεργασία του ιστορικού των commits. Μετά την κυκλοφορία, η διόρθωση θα είναι διαφορετική ανάλογα με τα εργαλεία και τις διαδικασίες που χρησιμοποιείτε. #### Όταν χρησιμοποιήσατε έναν τύπο *όχι* της προδιαγραφής, π.χ. `feet` αντί για `feat` Στο χειρότερο σενάριο, δεν είναι το τέλος του κόσμου αν ένα commit που δεν πληροί την προδιαγραφή Conventional Commits ενσωματωθεί. Σημαίνει απλώς ότι το commit θα παραλειφθεί από εργαλεία που βασίζονται στην προδιαγραφή. ### Πρέπει όλοι οι συνεισφέροντες μου να χρησιμοποιούν την προδιαγραφή Conventional Commits; Όχι! Εάν χρησιμοποιείτε μια ροή εργασίας βασισμένη στο squash στο Git, οι κύριοι συντηρητές μπορούν να επεξεργαστούν τα μηνύματα των commits καθώς τα συγχωνεύουν—χωρίς να προσθέτουν φόρτο εργασίας στους περιστασιακούς συνεισφέροντες. Μια κοινή ροή εργασίας για αυτό είναι το σύστημά σας git να κάνει αυτόματα squash τα commits από ένα pull request και να παρουσιάζει μια φόρμα στον κύριο συντηρητή για να εισαγάγει το σωστό μήνυμα git commit για τη συγχώνευση. ### Πώς χειρίζονται τα Conventional Commits τα revert commits; Η αναίρεση κώδικα μπορεί να είναι περίπλοκη: αναιρείτε πολλαπλά commits; αν αναιρέσετε ένα χαρακτηριστικό, θα πρέπει η επόμενη έκδοση να είναι patch; Τα Conventional Commits δεν προσπαθούν ρητά να ορίσουν τη συμπεριφορά αναίρεσης. Αντ' αυτού, το αφήνουμε στους δημιουργούς εργαλείων να χρησιμοποιήσουν την ευελιξία των τύπων (types) και των υποσέλιδων (footers) για να αναπτύξουν τη λογική τους για το χειρισμό των αναιρέσεων. Μια σύσταση είναι να χρησιμοποιήσετε τον τύπο `revert` και ένα υποσέλιδο που αναφέρεται στα SHA των commits που αναιρούνται: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.hi.md ================================================ --- draft: false aliases: ["/hi/"] --- # कन्वेंशनल कमिट्स 1.0.0 ## Summary ## सारांश कन्वेंशनल कमिट्स विनिर्देश कमिट संदेशों पर एक हल्का सम्मेलन है। यह एक स्पष्ट कमिट इतिहास बनाने के लिए नियमों का एक आसान सेट प्रदान करता है; जिससे स्वचालित उपकरण लिखना आसान हो जाता है। यह सम्मेलन [SemVer](http://semver.org), कमिट संदेशों में किए गए फीचर्स, फिक्सेस और ब्रेकिंग चेंजेस का वर्णन करके के साथ जुड़ता है। कमिट संदेश को निम्नानुसार संरचित किया जाना चाहिए: --- ``` [वैकल्पिक स्कोप]: <विवरण> [वैकल्पिक बॉडी] [वैकल्पिक फुटर(स)] ``` ---
कमिट में निम्नलिखित संरचनात्मक तत्व होते हैं, आपके पुस्तकालय के उपभोक्ताओं को इरादा बताने के लिए: 1. **fix:** `fix` _टाइप_ का एक कमिट आपके कोडबेस में एक बग को पैच करता है (यह सेमैंटिक वर्जनिंग में [`PATCH`](http://semver.org/#summary) से संबंधित है)। 1. **feat:** `feat` _टाइप_ का एक कमिट कोडबेस में एक नई फीचर पेश करता है (यह सेमैंटिक वर्जनिंग में [`MINOR`](http://semver.org/#summary) से संबंधित है)। 1. **BREAKING CHANGE:** एक कमिट जिसमें `BREAKING CHANGE:` फुटर है, या टाइप/स्कोप के बाद `!` जोड़ता है, एक ब्रेकिंग API चेंज पेश करता है (सेमैंटिक वर्जनिंग में [`MAJOR`](http://semver.org/#summary) से संबंधित)। एक BREAKING CHANGE किसी भी _टाइप_ के कमिट्स का हिस्सा हो सकता है। 1. `fix:` और `feat:` के अलावा अन्य _टाइप्स_ की अनुमति है, उदाहरण के लिए [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) ( [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) पर आधारित) `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, और अन्य की सिफारिश करता है। 1. `BREAKING CHANGE: <विवरण>` के अलावा अन्य _फुटर_ प्रदान किए जा सकते हैं और [git trailer format](https://git-scm.com/docs/git-interpret-trailers) के समान सम्मेलन का पालन करते हैं। अतिरिक्त टाइप्स कन्वेंशनल कमिट्स विनिर्देश द्वारा अनिवार्य नहीं हैं, और सेमैंटिक वर्जनिंग में कोई अंतर्निहित प्रभाव नहीं है (जब तक वे BREAKING CHANGE शामिल नहीं करते)।

एक स्कोप कमिट के टाइप को प्रदान किया जा सकता है, अतिरिक्त संदर्भ जानकारी प्रदान करने के लिए और कोष्ठक में समाहित है, जैसे `feat(parser): arrays parse करने की क्षमता जोड़ें`। ## उदाहरण ### विवरण और ब्रेकिंग चेंज फुटर के साथ कमिट संदेश ``` feat: provided config object को अन्य configs को extend करने की अनुमति दें BREAKING CHANGE: config file में `extends` key अब अन्य config files को extend करने के लिए इस्तेमाल किया जाता है ``` ### ब्रेकिंग चेंज पर ध्यान आकर्षित करने के लिए `!` के साथ कमिट संदेश ``` feat!: जब कोई प्रोडक्ट शिप हो जाए तो कस्टमर को email भेजें ``` ### स्कोप और `!` के साथ कमिट संदेश ब्रेकिंग चेंज पर ध्यान आकर्षित करने के लिए ``` feat(api)!: जब कोई प्रोडक्ट शिप हो जाए तो कस्टमर को email भेजें ``` ### `!` और BREAKING CHANGE फुटर दोनों के साथ कमिट संदेश ``` chore!: Node 6 के लिए सपोर्ट छोड़ दें BREAKING CHANGE: Node 6 में उपलब्ध नहीं होने वाले JavaScript features का इस्तेमाल करें। ``` ### बॉडी के बिना कमिट संदेश ``` docs: CHANGELOG की spelling सही करें ``` ### स्कोप के साथ कमिट संदेश ``` feat(lang): Polish language जोड़ें ``` ### मल्टी-पैराग्राफ बॉडी और मल्टीपल फुटर के साथ कमिट संदेश ``` fix: requests के racing को रोकें एक request id और latest request का reference पेश करें। latest request से अलावा आने वाले responses को खारिज करें। timeouts को हटा दें जो racing issue को कम करने के लिए इस्तेमाल किए जाते थे लेकिन अब obsolete हैं। Reviewed-by: Z Refs: #123 ``` ## Specification ## पूरी विशिष्टता इस दस्तावेज़ में “जरूरी”("MUST"), “आवश्यक नहीं”("MUST NOT"), “आवश्यक”("REQUIRED"), “साझा करें”("SHALL"), “नहीं होगा”("SHALL NOT"), “चाहिए”("SHOULD"), “नहीं होना चाहिए”("SHOULD NOT"), “अनुशंसित”("RECOMMENDED"), “मई”(MAY"), और “वैकल्पिक”("OPTIONAL") कीवर्ड को [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) में वर्णित अनुसार व्याख्या किया जाना चाहिए। 1. कमिट्स को एक टाइप से शुरू होना चाहिए, जिसमें एक noun, `feat`, `fix`, आदि शामिल है, इसके बाद OPTIONAL स्कोप, OPTIONAL `!`, और REQUIRED terminal colon और space। 2. टाइप `feat` का इस्तेमाल तब किया जाना चाहिए जब एक कमिट आपके एप्लिकेशन या लाइब्रेरी में एक नई फीचर जोड़ता है। 3. टाइप `fix` का इस्तेमाल तब किया जाना चाहिए जब एक कमिट आपके एप्लिकेशन के लिए एक बग फिक्स का प्रतिनिधित्व करता है। 4. एक स्कोप टाइप के बाद प्रदान किया जा सकता है। एक स्कोप को कोडबेस के एक सेक्शन का वर्णन करने वाले noun से मिलकर होना चाहिए, कोष्ठक में घिरा हुआ, जैसे `fix(parser):` 5. एक विवरण टाइप/स्कोप prefix के बाद colon और space के तुरंत बाद आना चाहिए। विवरण कोड चेंजेस का एक छोटा सारांश है, जैसे _fix: array parsing issue जब string में multiple spaces थे_। 1. एक लंबा कमिट बॉडी विवरण के बाद प्रदान किया जा सकता है, कोड चेंजेस के बारे में अतिरिक्त संदर्भ जानकारी प्रदान करके। बॉडी को विवरण के बाद एक blank line से शुरू होना चाहिए। 2. एक कमिट बॉडी free-form है और किसी भी संख्या में newline separated paragraphs से मिलकर हो सकता है। 3. एक या अधिक फुटर बॉडी के बाद एक blank line के बाद प्रदान किए जा सकते हैं। प्रत्येक फुटर को एक word token से मिलकर होना चाहिए, इसके बाद या तो `:` या `#` separator, इसके बाद एक string value (यह [git trailer convention](https://git-scm.com/docs/git-interpret-trailers) से प्रेरित है)। 4. एक फुटर के token में whitespace characters की जगह `-` का इस्तेमाल करना चाहिए, जैसे `Acked-by` (यह फुटर सेक्शन को multi-paragraph बॉडी से अलग करने में मदद करता है)। `BREAKING CHANGE` के लिए एक अपवाद बनाया गया है, जो token के रूप में भी इस्तेमाल किया जा सकता है। 5. एक फुटर की value में spaces और newlines हो सकते हैं, और parsing तब समाप्त होना चाहिए जब अगला valid footer token/separator pair observed हो। 6. ब्रेकिंग चेंजेस को कमिट के टाइप/स्कोप prefix में या फुटर में entry के रूप में इंगित किया जाना चाहिए। 7. यदि फुटर के रूप में शामिल किया गया है, तो एक ब्रेकिंग चेंज uppercase text BREAKING CHANGE से मिलकर होना चाहिए, इसके बाद colon, space, और विवरण, जैसे _BREAKING CHANGE: environment variables अब config files पर precedence लेते हैं_। 8. यदि टाइप/स्कोप prefix में शामिल किया गया है, तो ब्रेकिंग चेंजेस को `!` से इंगित किया जाना चाहिए `:` से पहले। यदि `!` इस्तेमाल किया गया है, तो `BREAKING CHANGE:` फुटर सेक्शन से omitted किया जा सकता है, और कमिट विवरण ब्रेकिंग चेंज का वर्णन करने के लिए इस्तेमाल किया जाएगा। 9. `feat` और `fix` के अलावा अन्य टाइप्स आपके कमिट संदेशों में इस्तेमाल किए जा सकते हैं, जैसे _docs: update ref docs._। 10. कन्वेंशनल कमिट्स बनाने वाली information units को implementors द्वारा case sensitive नहीं माना जाना चाहिए, BREAKING CHANGE के अपवाद के साथ जो uppercase होना चाहिए। 11. BREAKING-CHANGE को BREAKING CHANGE के समानार्थी होना चाहिए, जब फुटर में token के रूप में इस्तेमाल किया जाए। ## कन्वेंशनल कमिट्स क्यों इस्तेमाल करें * स्वचालित रूप से CHANGELOGs जनरेट करना। * स्वचालित रूप से सेमैंटिक वर्जन bump निर्धारित करना (landed कमिट्स के टाइप्स पर आधारित)। * चेंजेस की nature को teammates, the public, और अन्य stakeholders को बताना। * बिल्ड और publish प्रोसेस ट्रिगर करना। * लोगों को आपके प्रोजेक्ट्स में contribute करना आसान बनाना, उन्हें एक अधिक structured कमिट इतिहास explore करने की अनुमति देकर। ## FAQ ## सामान्य प्रश्न ### प्रारंभिक development phase में कमिट संदेशों से कैसे निपटें? हम सिफारिश करते हैं कि आप ऐसा behave करें जैसे आपने पहले ही प्रोडक्ट रिलीज़ कर दिया हो। आमतौर पर *कोई*, भले ही यह आपके fellow software developers हों, आपके software का इस्तेमाल कर रहा है। वे जानना चाहेंगे कि क्या fixed है, क्या breaks है आदि। ### कमिट title में टाइप्स uppercase या lowercase हैं? कोई भी casing इस्तेमाल की जा सकती है, लेकिन consistent रहना सबसे अच्छा है। ### क्या करें यदि कमिट एक से अधिक कमिट टाइप्स के अनुरूप है? जब भी संभव हो, वापस जाकर multiple कमिट्स बनाएं। कन्वेंशनल कमिट्स के लाभों में से एक यह है कि यह हमें अधिक organized कमिट्स और PRs बनाने के लिए drive करता है। ### क्या यह rapid development और fast iteration को discourage नहीं करता? यह disorganized तरीके से fast move करने को discourage करता है। यह आपको long term में multiple प्रोजेक्ट्स में fast move करने में मदद करता है varied contributors के साथ। ### क्या कन्वेंशनल कमिट्स developers को उनके द्वारा किए जाने वाले कमिट्स के टाइप को limit करने के लिए lead कर सकता है क्योंकि वे provided टाइप्स में सोच रहे होंगे? कन्वेंशनल कमिट्स हमें fixes जैसे कुछ टाइप्स के अधिक कमिट्स बनाने के लिए encourage करता है। इसके अलावा, कन्वेंशनल कमिट्स की flexibility आपकी team को अपने own टाइप्स develop करने और समय के साथ उन टाइप्स को change करने की अनुमति देती है। ### यह SemVer से कैसे संबंधित है? `fix` टाइप कमिट्स को `PATCH` रिलीज़ में translate किया जाना चाहिए। `feat` टाइप कमिट्स को `MINOR` रिलीज़ में translate किया जाना चाहिए। कमिट्स में `BREAKING CHANGE` के साथ, टाइप की परवाह किए बिना, को `MAJOR` रिलीज़ में translate किया जाना चाहिए। ### कन्वेंशनल कमिट्स विनिर्देश के अपने extensions को कैसे version करें, जैसे `@jameswomack/conventional-commit-spec`? हम सिफारिश करते हैं कि इस विनिर्देश के अपने extensions को रिलीज़ करने के लिए SemVer का इस्तेमाल करें (और हम आपको ये extensions बनाने के लिए encourage करते हैं!) ### क्या करें यदि मैंने accidentally गलत कमिट टाइप इस्तेमाल किया? #### जब आपने spec का टाइप इस्तेमाल किया लेकिन सही टाइप नहीं, जैसे `fix` instead of `feat` मर्ज या रिलीज़ से पहले, हम `git rebase -i` का इस्तेमाल करके कमिट इतिहास edit करने की सिफारिश करते हैं। रिलीज़ के बाद, cleanup आपके द्वारा इस्तेमाल किए जाने वाले tools और processes के अनुसार अलग होगा。 #### जब आपने spec का टाइप *नहीं* इस्तेमाल किया, जैसे `feet` instead of `feat` worst case scenario में, यह दुनिया का अंत नहीं है यदि एक कमिट land करता है जो कन्वेंशनल कमिट्स विनिर्देश को पूरा नहीं करता। इसका मतलब सिर्फ इतना है कि वह कमिट spec पर आधारित tools द्वारा missed हो जाएगा। ### क्या मेरे सभी contributors को कन्वेंशनल कमिट्स विनिर्देश इस्तेमाल करना जरूरी है? नहीं! यदि आप Git पर squash based workflow इस्तेमाल करते हैं तो lead maintainers कमिट संदेशों को clean up कर सकते हैं जैसे वे merged होते हैं—casual committers पर कोई workload नहीं जोड़ते। इसके लिए एक common workflow यह है कि आपका git system स्वचालित रूप से pull request से कमिट्स को squash करता है और lead maintainer को merge के लिए proper git कमिट संदेश enter करने के लिए एक form प्रस्तुत करता है। ### कन्वेंशनल कमिट्स revert कमिट्स को कैसे handle करता है? कोड revert करना complicated हो सकता है: क्या आप multiple कमिट्स revert कर रहे हैं? यदि आप एक फीचर revert करते हैं, तो क्या अगली रिलीज़ instead एक patch होनी चाहिए? कन्वेंशनल कमिट्स revert behavior को define करने के लिए explicit effort नहीं करता। इसके बजाय हम इसे tooling authors पर छोड़ते हैं कि वे reverts को handle करने के लिए _टाइप्स_ और _फुटर_ की flexibility का इस्तेमाल करें। एक recommendation `revert` टाइप इस्तेमाल करना है, और एक फुटर जो revert किए जा रहे कमिट SHAs का reference देता है: ``` revert: आइए हम कभी भी noodle incident की बात न करें Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.hy.md ================================================ --- draft: false aliases: ["/hy/"] --- # Conventional Commits 1.0.0 ## Ամփոփում Conventional Commits-ը իրենից ներկայացնում է թեթև կոնվենցիաներ՝ commit հաղորդագրությունների վրա։ Այն ապահովում է պարզ commit-ների պատմություն ստեղծելու հեշտ եղանակ, ինչը հեշտացնում է ավտոմատացման գործիքների օգտագործումը։ Այս կոնվենցիան համընկնում է [SemVer](http://semver.org)-ի հետ, նկարագրելով commit հաղորդագրություններում կատարված առանձնահատկությունները, ուղղումները և փոփոխությունները: Commit հաղորդագրությունները պետք է ունենան հետևյալ կառուցվածքը․ --- ``` <տիպ>[ոչ պարտադիր շրջանակ]: <նկարագրություն> [ոչ պարտադիր մարմին] [ոչ պարտադիր վերջավորություն(ներ)] ``` ---
Commit-ը պարունակում է հետևյալ կառուցվածքային տարրերը՝ ձեր փոփոխությունների մտադրությունը հաղորդելու համար. 1. **fix:** այն commit-ները, որոնք պատկանում են `fix` _տիպին_ , իրենցից ներկայացնում են բագերի ուղղումներ (այն համապատասխանում է Semantic Versioning-ի [`PATCH`](http://semver.org/#summary) տեսակին)։ 1. **feat:** այն commit-ները, որոնք պատկանում են `feat` _տիպին_ , իրենցից ներկայացնում են նոր հատկանիշների ավելացում (այն համապատասխանում է Semantic Versioning-ի [`MINOR`](http://semver.org/#summary) տեսակին)։ 1. **BREAKING CHANGE:** այն commit-ները, որոնք ունեն `BREAKING CHANGE:` վերջավորությունը, կամ ընդգրկում են `!` նշանը, տիպից(շրջանակից) հետո, իրենցից ներկայացնում են կարևոր կամ բեկումնային փոփոխություններ (այն համապատասխանում է Semantic Versioning-ի [`MAJOR`](http://semver.org/#summary) տեսակին)։ BREAKING CHANGE-ը կարող է հանդիսանալ ցանկացած տիպի commit-ի մաս։ 1. `fix:`-ից և `feat:`-ից բացի այլ տիպերի օգտագործումը թույլատրվում է, օրինակ՝ [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config) (հիմնվելով [Angular-ի կոնվենցիայի](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) վրա) առաջարկում է `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` և այլն: 1. `BREAKING CHANGE: ` բացի այլ վերջավորություններ կարող են տրամադրվել և հետևել [git թրեյլերի ձևաչափ](https://git-scm.com/docs/git-interpret-trailers)-ին հարակից կոնվենցիաներին։ Լրացուցիչ տիպերը պարտադիր չեն Conventional Commits-ի դասակարգմամբ և չունեն անուղղակի ազդեցություն իմաստային տարբերակման մեջ (եթե դրանք չեն ներառում BREAKING CHANGE):

Հանձնարարականի տիպին կարող է տրվել շրջանակ՝ լրացուցիչ համատեքստային ինֆորմացիա տրամադրելու համար։ Այն օգտագործվում է փակագծերի մեջ, հետևյալ կերպ՝ `feat(parser): add ability to parse arrays`: ## Օրինակներ ### Commit հաղորդագրություն՝ նկարագրով և breaking change վերջավորությունով ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit հաղորդագրություն՝ `!` նշանով, որպեսզի ուշադրություն գրավենք կատարված կարևոր փոփոխությունների համար ``` feat!: send an email to the customer when a product is shipped ``` ### Commit հաղորդագրություն՝ շրջանակով և `!` նշանով, որպեսզի ուշադրություն գրավենք կատարված կարևոր փոփոխությունների համար ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit հաղորդագրություն՝ միաժամանակ և՛ `!` նշանով, և՛ BREAKING CHANGE վերջավորությունով ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit հաղորդագրություն՝ առանց մարմնի ``` docs: correct spelling of CHANGELOG ``` ### Commit հաղորդագրություն՝ շրջանակով ``` feat(lang): add Polish language ``` ### Commit հաղորդագրություն՝ մի քանի պարագրաֆ մարմնով և մի քանի վերջավորություններով ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Հստակեցում “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” բառերն այս փաստաթղթում պետք է մեկնաբանվեն այնպես, ինչպես նկարագրված է [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)-ում։ 1. Commit-ները պետք է ունեն տիպ՝ նախածանցի տեսքով, որը պետք է բաղկացած լինի գոյականից, `feat`, `fix` և այլն, որին հաջորդում են ոչ պարտադիր շրջանակը, ոչ պարտադիր `!`-ը և պարտադիր վերջակետ ու բացատ: 1. `feat` տիպը պետք է օգտագործել այն ժամանակ, երբ Ձեր ծրագրում ավելացնում եք նոր հատկանիշներ։ 1. `fix` տիպը պետք է օգտագործել այն ժամանակ, երբ Ձեր ծրագրում կատարում եք ուղղումներ։ 1. Շրջանակը պետք է նշել տիպից հետո՝ փակագծերի մեջ։ Այն կարող է լինել Ձեր փոփոխած հատվածի վերնագիրը, օրինակ` `fix(parser):`։ 1. Նկարագիրը պետք է գրված լինի տիպից կամ շրջանակից հետո՝ պահելով դրանց միջև վերջակետ և բացատ։ Այն Ձեր կատարած փոփոխությունների կարճ նկարագիրն է, օրինակ՝ _fix: array parsing issue when multiple spaces were contained in string_։ 1. Մարմինը կարելի է գրել նկարագրությունից հետո։ Այն Ձեր կատարած փոփոխությունների լայն նկարագիրն է։ Այն պետք է պահի մեկ դատարկ տող՝ նկարագրի միջև։ 1. Commit-ի մարմինը ունի ազատ գրելաձև, կարող է պարունակել տառեր, թվեր, մի քանի պարբերություններ և այլն։ 1. Մեկ կամ ավելի վերջավորությունները պետք է ունենան մեկ դատարկ տող՝ առանձնացվելով մարմնից(ավելին կարող եք կարդալ [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)-ում)։ 1. Վերջավորության նշանը պետք Է օգտագործի `-`՝ բացատ նիշերի փոխարեն, օրինակ՝ `Acked-by` (սա օգնում է տարբերակել վերջավորությունը բազմաբնույթ պարբերությունից): Բացառություն է արվում `BREAKING CHANGE-ի համար, որը կարող Է օգտագործվել նաև որպես նշան: 1. Վերջավորության արժեքը կարող Է պարունակել բացատներ և նոր տողեր, և վերլուծությունը պետք Է ավարտվի, երբ հաջորդ վավեր վերջավորությունը նկատվում է: 1. Breaking change-երը պետք է նշված լինեն տիպում կամ շրջանակում, և կամ էլ վերջավորության մեջ։ 1. Եթե գոյություն ունի վերջավորություն, ապա breaking change-ը պետք է լինի մեծատառ, օրինակ՝ _BREAKING CHANGE: environment variables now take precedence over config files_։ 1. Եթե ներառված է տիպի(շրջանակի) նախածանցում, ապա խախտման փոփոխությունները պետք Է նշված լինեն `!` `:`-ից անմիջապես առաջ: Եթե `!`-ն օգտագործվում է, `BREAKING CHANGE`-ը կարող է բաց թողնել ստորագիր հատվածից, և պարտավորության նկարագրությունը պետք Է օգտագործվի՝ նկարագրելու փոփոխությունը: 1. `feat` և `fix` տիպերից բացի կարող են օգտագործվել Ձեր commit հաղորդագրություններում, օրինակ՝ _docs: updated ref docs._։ 1. Այն ինֆորմացիոն տարրերը, որոնք կազմված են Conventional Commits-ի MUST NOT տեսակից իրականացնողների կողմից դիտարկվում են, որպես գործի զգայուն հատված, բացառությամբ BREAKING CHANGE-ի որը պետք է լինի մեծատառ։ 1. BREAKING-CHANGE MUST-ը BREAKING CHANGE հոմանիշն է, երբ օգտագործվում է, որպես վերջավորություն։ ## Ինչ՞ու օգտագործել Conventional Commits-ը * Ավտոմատ կերպով գեներացնում են CHANGELOG-ներ։ * Ավտոմատ կերպով կատարում են տարբերակների բարձրացում (հիմնվելով կատարված commit-ների տեսակի վրա)։ * Փոփոխությունների բնույթի հաղորդում թիմակիցներին, հանրությանը և այլ շահագրգիռ կողմերին: * Ստեղծման և հրապարակման գործընթացների ակտիվացում: * Առավել հեշտացնում է նպաստումը Ձեր նախագծին այլ մարդկանց կողմից՝ թույլ տալով նրանց ուսումնասիրել ավելի ընթեռնելի commit-ների պատմություն: ## Հ․Տ․Հ․ ### Ինչպե՞ս պետք է վարվեմ commit հաղորդագրությունների հետ նախնական զարգացման փուլում: Մենք խորհուրդ ենք տալիս շարունակել այնպես, կարծես արդեն թողարկել եք պրոդուկտը: Սովորաբար *ինչ-որ մեկը*, նույնիսկ եթե դա ձեր գործընկեր ծրագրավորողներն են, օգտագործում է ձեր ծրագրաշարը: Նրանք կցանկանան իմանալ, թե ինչն է շտկված, ինչն է կոտրվում և այլն: ### Commit-ների վերնագրի տեսակները մեծատառե՞ն են, թե՞ փոքրատառ: Ցանկացած միջոց կարող է օգտագործվել, բայց ավելի լավ է հետևողական լինել և օգտագործել դրանցից որևէ մեկը: ### Ի՞նչ անել, եթե commit-ը համապատասխանում է commit-ների մեկից ավելի տեսակներին: Վերադարձեք և հնարավորության դեպքում մի քանի commit-ներ կատարեք: Conventional Commits-ը օգտագործելու իմաստներից մեկը՝ մեր commit հաղորդագրություններն ու PR-ները ավելի կազմակերպված դարձնելն է: ### Արդյո՞ք սա չի խանգարում պրոյեկտի արագ զարգացմանը և արագ կրկնմանը: Այն խանգարում է արագ շարժվել անկազմակերպ կերպով: Այն օգնում է Ձեզ երկարաժամկետ արագ շարժվել բազմաթիվ նախագծերի մեջ՝ տարբեր ներդրողների հետ: ### Հնարավո՞ր է, որ Conventional Commits-ը ծրագրավորողներին սահմանափակի իրենց կատարած commit-ների տեսակը, քանի որ նրանք կմտածեն տրամադրված տեսակների վրա: Conventional Commits-ը մեզ խրախուսում է ավելի շատ կատարել որոշակի տեսակի commit-ներ, ինչպիսիք են ուղղումները: Բացի դրանից, Conventional Commits-ի ճկունությունը թույլ է տալիս Ձեր թիմին գտնել իրենց տեսակները և ժամանակի ընթացքում փոխել դրանք: ### Ինչպե՞ս է դա կապված SemVer-ի հետ: `fix` տեսակի պարտավորությունները պետք է թարգմանվեն `PATCH` թողարկումներով: `feat` տեսակի պարտավորությունները պետք է թարգմանվեն `MINOR` թողարկումներով: Հանձնարարություններում `BREAKING CHANGE` ունեցող պարտավորությունները, անկախ տեսակից, պետք է թարգմանվեն `MAJOR` թողարկումներով: ### Ինչպես պետք է տարբերակեմ իմ ընդլայնումները Conventional Commits-ի սպեցիֆիկացիայի համար (օրինակ `@jameswomack/conventional-commit-spec`): Մենք խորհուրդ ենք տալիս օգտագործել SemVer-ը, որպեսզի թողարկեք ձեր սեփական ընդլայնումները այս բնութագրին (և խրախուսում ենք ձեզ կատարել այս ընդլայնումները:) ### Ի՞նչ անեմ, եթե պատահաբար օգտագործեմ սխալ commit-ի տեսակը: #### Երբ դուք օգտագործում եք այնպիսի տեսակ, որը համապատասխանում է բնութագրին, բայց ոչ ճիշտ, օրինակ. `fix`՝ `feat`-ի փոխարեն Նախքան սխալը միաձուլելը կամ բաց թողնելը, մենք խորհուրդ ենք տալիս օգտագործել `git rebase -i`՝ կատարման պատմությունը խմբագրելու համար: Թողարկումից հետո մաքրումը կտարբերվի՝ կախված ձեր օգտագործած գործիքներից և գործընթացներից: #### Երբ դուք օգտագործում եք հատուկ *ոչ* տեսակ, օրինակ. `feet`՝ `feat`-ի փոխարեն Վատագույն սցենարի դեպքում աշխարհի վերջը չէ, եթե commit-ը վայրէջք կատարի, որը չի համապատասխանում Conventional Commits-ի պահանջներին: Դա պարզապես նշանակում է, որ commit-ը բաց կթողնի այն գործիքները, որոնք հիմնված են բնութագրերի վրա: ### Արդյո՞ք իմ բոլոր մասնակիցները պետք է օգտագործեն Conventional Commits-ի հստակեցումը: Ո՛չ։ Եթե դուք օգտագործում եք squash-ի վրա հիմնված աշխատանքային հոսք Git-ի առաջատար սպասարկիչները կարող են մաքրել commit հաղորդագրությունները, քանի որ դրանք միաձուլվում են՝ առանց աշխատանքային ծանրաբեռնվածության ավելացման պատահական commiter-ին: Սրա համար ընդհանուր աշխատանքային հոսքն այն է, որ ձեր git համակարգը ինքնաբերաբար PR-ը կմիաձուլի մեկ squash commit-ի մեջ, որպեսզի առաջատար սպասարկիչը մուտքագրի համապատասխան git commit հաղորդագրությունը միաձուլման համար: ### Ինչպե՞ս են Conventional Commits-ը վերաբերվում վերադարձի(revert) commit-ներին: Կոդը վերադարձնելը կարող է բարդ լինել. դուք վերադարձնու՞մ եք մի քանի commit-ներ: եթե վերադարձնեք որևէ հատկանիշ(feature), հաջորդ թողարկումը դրա փոխարեն կարկատա՞կ պետք է լինի: Conventional Commits-ը բացահայտ ջանքեր չի գործադրում հետադարձ վարքագիծը սահմանելու համար: Փոխարենը թողնում ենք հեղինակներին օգտագործել _types_-ի և _footers_-ի ճկունությունը՝ զարգացնելու իրենց տրամաբանությունը հետադարձումների հետ աշխատելու համար: Առաջարկություններից մեկն է օգտագործել `revert` տիպը և վերջավորություն, որը հղում է կատարում վերադարձվող SHA-ներին՝ ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.id.md ================================================ --- draft: false aliases: ["/id/"] --- # Conventional Commits 1.0.0 ## Ringkasan Conventional Commits adalah perjanjian sederhana tentang cara menulis pesan komit. Ini menjelaskan sekumpulan aturan sederhana untuk membuat riwayat komit yang jelas; yang memudahkan untuk membuat alat otomatis di atasnya. Perjanjian ini sesuai dengan [SemVer](http://semver.org/lang/id/), dengan menjelaskan suatu fitur (features), perbaikan (fixes), perubahan yang merusak (breaking changes) yang dimuat dalam pesan komit. Pesan komit harus tersusun sebagai berikut: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
Komit ini memiliki elemen-elemen struktural berikut untuk menjelaskan maksud kepada pengguna pustaka: 1. **fix:** komit _tipe_ `fix` untuk perbaikan celah (bug) dalam kode Anda (ini berkaitan dengan [`PATCH`](http://semver.org/#summary) di Semantic Versioning). 1. **feat:** komit _tipe_ `feat` memperkenalkan suatu fitur (feature) baru dalam kode Anda (ini berkaitan dengan [`MINOR`](http://semver.org/#summary) di Semantic Versioning). 1. **BREAKING CHANGE:** komit yang berisi footer `BREAKING CHANGE:`, atau tambahkan `!` setelah type/scope, memperkenalkan perubahan yang merusak API (ini berkaitan dengan [`MAJOR`](http://semver.org/#summary) di Semantic Versioning). BREAKING CHANGE dapat diterapkan pada semua _tipe_ komit. 1. _types_ selain `fix:` dan `feat:` diperbolehkan, sebagai contoh [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (berdasarkan pada [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) disarankan `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, dan lainnya. 1. _footers_ daripada `BREAKING CHANGE: ` dapat disediakan dan mengikuti konvensi yang mirip dengan [format git trailer](https://git-scm.com/docs/git-interpret-trailers). Tipe tambahan tidak di amanatkan oleh spesifikasi conventional commits, dan tidak ada efek implisit dalam Semantic Versioning (kecuali mereka termasuk BREAKING CHANGE).

Cakupan (scope) dapat disediakan ke tipe komit untuk memberikan informasi kontekstual tambahan dan terkandung dalam kurung, misalnya, `feat(parser): add ability to parse arrays`. ## Contoh ### Pesan komit dengan deskripsi dan breaking change di footer ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Pesan komit dengan `!` untuk menarik perhatian pada breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### Pesan komit dengan scope dan `!` untuk menarik perhatian pada breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Pesan komit dengan keduanya `!` dan footer BREAKING CHANGE ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Pesan komit tanpa body ``` docs: correct spelling of CHANGELOG ``` ### Pesan komit dengan scope ``` feat(lang): add polish language ``` ### Pesan komit dengan badan multi-paragraf dan multi-footer ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Spesifikasi Kata kunci “HARUS”, “TIDAK BOLEH”, “DIBUTUHKAN”, “SEHARUSNYA”, “JANGAN SAMPAI”, “SEBAIKNYA”, “SEBAIKNYA TIDAK”, “DIREKOMENDASIKAN”, “BISA”, dan “OPSIONAL” di dokumen ini sesuai dengan [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Komit HARUS (MUST) diawali dengan tipe, yang terdiri dari kata benda, `feat`, `fix`, dll., diikuti dengan scope OPSIONAL (OPTIONAL) `!`, dan DIBUTUHKAN (REQUIRED) terminal colon dan spasi. 1. Tipe `feat` HARUS (MUST) digunakan ketika komit menambahkan fitur baru ke aplikasi atau pustaka Anda. 1. Tipe `fix` HARUS (MUST) digunakan ketika komit merepresentasikan perbaikan bug untuk aplikasi Anda. 1. Scope BISA (MAY) dicantumkan setelah tipe. Scope HARUS (MAY) terdiri dari kata benda yang menggambarkan bagian dari kode yang dikelilingi tanda kurung, misalnya, e.g., `fix(parser):` 1. Deskripsi HARUS (MUST) segera mengikuti spasi setelah awalan type/scope. Deskripsi adalah ringkasan singkat dari perubahan kode, misalnya, _fix: array parsing issue when multiple spaces were contained in string_. 1. Body yang lebih panjang BISA (MAY) disediakan setelah deskripsi singkat, memberikan informasi kontekstual tambahan tentang perubahan kode. Body HARUS (MUST) memulai satu baris kosong setelah deskripsi. 1. Body komit adalah bentuk bebas dan BISA (MAY) terdiri dari sejumlah paragraf terpisah baris baru. 1. Satu atau lebih footer BISA (MAY) disediakan satu baris kosong setelah badan. Setiap footer HARUS (MUST) terdiri dari token kata, diikuti oleh pemisah `:` atau `#`, diikuti oleh nilai string (ini terinspirasi oleh [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. Token footer HARUS (MUST) menggunakan `-` sebagai ganti karakter spasi putih, mis., `Acked-by` (ini membantu membedakan bagian footer dari badan multi-paragraf). Pengecualian dibuat untuk `BREAKING CHANGE`, yang BISA (MAY) juga digunakan sebagai token. 1. Nilai footer BISA (MAY) berisi spasi dan baris baru, dan penguraian HARUS (MUST) berakhir ketika pasangan token/pemisah footer yang berlaku berikutnya diamati. 1. Melanggar perubahan HARUS (MUST) ditunjukkan dalam tipe / lingkup awalan dari komit, atau sebagai entri dalam catatan kaki. 1. Jika dimasukkan sebagai footer, perubahan yang melanggar HARUS (MUST) terdiri dari teks huruf besar BREAKING CHANGE, diikuti oleh titik dua, spasi, dan deskripsi, mis., _BREAKING CHANGE: variabel lingkungan sekarang diutamakan daripada file konfigurasi_. 1. Jika termasuk dalam awalan, memecah perubahan HARUS (MUST) ditunjukkan oleh `!` Segera sebelum `:`. Jika `!` Digunakan, `BREAKING CHANGE:` BISA (MAY) dihapus dari bagian footer, dan deskripsi commit HARUS (MUST) digunakan untuk menjelaskan perubahan yang melanggar. 1. Jenis selain `feat` dan `fix` BISA (MAY) digunakan dalam pesan komit Anda, mis., _docs: updated ref docs._ 1. Unit-unit informasi yang membentuk konvensional melakukan TIDAK BOLEH (MUST NOT) diperlakukan sebagai case sensitif oleh implementor, dengan pengecualian BREAKING CHANGE yang HARUS (MUST) huruf besar. 1. BREAKING-CHANGE HARUS (MUST) identik dengan BREAKING CHANGE, bila digunakan sebagai token di footer. ## Mengapa menggunakan Conventional Konvensional * Secara otomatis menghasilkan CHANGELOGs. * Secara otomatis menentukan versi semantic (Berdasarkan tipe komit yang dilakukan). * Mengomunikasikan sifat perubahan kepada rekan setim, publik, dan pemangku kepentingan lainnya. * Memicu proses pembuatan dan publikasi. * Mempermudah orang untuk berkontribusi pada proyek Anda, dengan memungkinkan mereka untuk menjelajah riwayat komit yang lebih terstruktur. ## FAQ ### Bagaimana saya harus berurusan dengan pesan komit pada fase pengembangan awal? Kami menyarankan Anda melanjutkan seolah-olah Anda sudah merilis produk. Biasanya *seseorang*, bahkan jika itu sesama pengembang perangkat lunak Anda, menggunakan perangkat lunak Anda. Mereka ingin tahu apa yang diperbaiki, apa yang rusak, dll. ### Apakah tipe dalam komit menggunakan judul huruf besar atau kecil? Casing apa pun dapat digunakan, tetapi yang terbaik adalah konsisten. ### Apa yang harus saya lakukan jika komit sesuai dengan lebih dari satu tipe komit? Kembalilah dan buat beberapa komit kapan pun memungkinkan. Bagian dari manfaat Conventional Commits adalah kemampuannya mendorong kami untuk membuat komitmen dan PR yang lebih terorganisir. ### Tidakkah ini menghambat pengembangan yang cepat dan iterasi yang cepat? Ini mencegah bergerak cepat dengan cara yang tidak teratur. Ini membantu Anda dapat bergerak cepat jangka panjang di berbagai proyek dengan kontributor yang bervariasi. ### Mungkinkah Komitmen Konvensional membuat pengembang membatasi jenis komitmen yang mereka buat karena mereka akan memikirkan jenis yang disediakan? Komitmen Konvensional mendorong kita untuk membuat lebih banyak jenis komitmen tertentu seperti perbaikan. Selain itu, fleksibilitas Komitmen Konvensional memungkinkan tim Anda untuk membuat tipe mereka sendiri dan mengubah tipe-tipe itu seiring waktu. ### Bagaimana ini berhubungan dengan SemVer? Komit tipe `fix` harus diterjemahkan ke rilis `PATCH`. Komit tipe `feat` harus diterjemahkan ke rilis `MINOR`. Komit dengan `BREAKING CHANGE` dalam komit, apa pun jenisnya, harus diterjemahkan ke rilis `MAJOR`. ### Bagaimana cara saya memberi versi ekstensi saya ke Spesifikasi Komitmen Konvensional, mis. `@jameswomack/commit-spec-konvensional`? Kami sarankan menggunakan SemVer untuk merilis ekstensi Anda sendiri ke spesifikasi ini (dan mendorong Anda untuk membuat ekstensi ini!) ### Apa yang harus saya lakukan jika saya secara tidak sengaja menggunakan tipe komit yang salah? #### Saat Anda menggunakan jenis yang memiliki spesifikasi tetapi bukan jenis yang benar, misalnya, `fix` bukan `feat` Sebelum menggabungkan atau merilis kesalahan, sebaiknya gunakan `git rebase -i` untuk mengedit riwayat komit. Setelah rilis, pembersihan akan berbeda sesuai dengan alat dan proses apa yang Anda gunakan. #### Saat Anda menggunakan jenis *bukan* spesifikasi, mis. `feet` bukannya `feat` Dalam skenario terburuk, hal ini bukanlah masalah besar jika terdapat komit yang tidak memenuhi spesifikasi conventional commit. Ini berarti komit akan dilewatkan oleh alat yang didasarkan pada spesifikasi. ### Apakah semua kontributor saya perlu menggunakan spesifikasi commit konvensional? Tidak! Jika Anda menggunakan alur kerja berbasis squash di pengelola Git dapat membersihkan pesan komit saat mereka digabung — menambahkan tidak ada beban kerja ke committers biasa. Alur kerja umum untuk ini adalah membuat sistem git Anda secara otomatis squash melakukan dari permintaan tarikan dan menyajikan formulir bagi pengelola utama untuk memasukkan pesan git commit yang tepat untuk penggabungan. ### Bagaimana Komit Konvensional menangani komit balik? Mengembalikan kode bisa rumit: apakah Anda mengembalikan banyak komit? jika Anda mengembalikan fitur, haruskah rilis berikutnya sebagai tambalan? Conventional Commits tidak membuat upaya eksplisit untuk mendefinisikan perilaku kembalikan. Alih-alih, kami menyerahkannya kepada perkakas penulis untuk menggunakan fleksibilitas _type_ dan _footers_ untuk mengembangkan logika mereka untuk menangani orang yang kembali. Satu rekomendasi adalah menggunakan tipe `revert`, dan _footer_ yang merujuk komit SHA yang sedang dikembalikan: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.it.md ================================================ --- draft: false aliases: ["/it/"] --- # Commit Convenzionali 1.0.0 ## Riepilogo La specifica Conventional Commits è una convenzione semplice da implementare per i messaggi dei commit. Fornisce un insieme di semplici regole per la creazione di una cronologia di commit esplicita; il che rende più facile utilizzare strumenti per automatizzare processi. Questa convenzione si completa con [SemVer](http://semver.org/lang/it/), descrivendo le funzionalità, la risoluzione di errori e l'introduzione di breaking changes fatte dei commit. I messaggi dei commit dovrebbero seguire la seguente struttura: --- ``` [contesto opzionale]: [corpo opzionale] [piè di pagina opzionali] ``` ---
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicare l'intento al consumatore della libreria: 1. **fix:** un commit di _tipo_ `fix` risolve un errore nel codice (correlato al [`PATCH`](http://semver.org/#summary) in un versionamento Semver). 1. **feat:** un commit di _tipo_ `feat` introduce una nuova funzionalità al codice (correlato al [`MINOR`](http://semver.org/#summary) in un versionamento Semver). 1. **BREAKING CHANGE:** un commit che contiene in un _piè di pagina_ `BREAKING CHANGE:`, o aggiunge un `!` subito dopo il _tipo_/_contesto_, all'inizio delle sezioni opzionali _corpo_ o _piè di pagina_, introduce una breaking API change (correlato al [`MAJOR`](http://semver.org/#summary) in un versionamento Semver). Una _BREAKING CHANGE_ può essere parte di un commit di qualsiasi _tipo_. 1. Sono ammessi ulteriori _tipi_ oltre `fix:` e`feat:`, per esempio [commitlint-config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (che si basa sulla [convenzione Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) raccomanda `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, ed altri. 1. Altri _piè di pagina_ oltre `BREAKING CHANGE: ` possono essere utilizzati e seguono ua specifica simile a [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Altri _tipi_ non sono mantenuti da questa specifica, e non hanno un effetto sul versionamento semver (a meno che non introducano una _BREAKING CHANGE_).
Un _contesto_ potrebbe essere aggiunto al _tipo_ di commit, al fine di offrire ulteriori informazioni contestuali. Da aggiungere tra delle parentesi tonde, Es: `feat(parser): add ability to parse arrays`. ## Esempi ### Messaggio di un commit con una _descrizione_ e una breaking change nel _piè di pagina_ ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Messaggio di un commit con un `!` per attirare l'attenzione su una breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### Messaggio di un commit con uno contesto e `!` per attirare attenzione ad una breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Messaggio di un commit con entrambe `!` e _BREAKING CHANGE_ a piè di pagina ``` feat!: send an email to the customer when a product is shipped BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### Messaggio di un commit senza una _descrizione_ ``` docs: correct spelling of CHANGELOG ``` ### Messaggio di un commit con uno _contesto_ ``` feat(lang): added polish language ``` ### Messaggio di un commit per un `fix` utilizzando il numero della issue (opzionale) ``` fix: minor typos in code see the issue for details on the typos fixed Reviewed-by: Z Refs: #133 ``` ## Specifica Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DEVE iniziare con un _tipo_, il quale consiste in un sostantivo, `feat`, `fix`, etc., seguito da un OPZIONALE `!`, e DEVE essere seguito dai due punti ed uno spazio. 1. Il _tipo_ `feat` DEVE essere usato quando un commit aggiunge una funzionalità all'applicazione o libreria. 1. Il _tipo_ `fix` DEVE essere usato quando un commit corregge un errore all'applicazione o libreria. 1. Un _contesto_ opzionale POTREBBE essere fornito dopo il _tipo_. Un _contesto_ rappresenta una sezione dell'applicazione o della libreria, il contenuto va racchiuso tra parentesi. Es: `fix(parser):` 1. Una _descrizione_ DEVE seguire immediatamente i due punti dopo il _tipo_ (con eventuale _contesto_). Per _descrizione_ si intende una breve spiegazione riguardo la modifica al codice. Es: _fix: array parsing issue when multiple spaces were contained in string_. 1. Un _corpo_ del commit più lungo POTREBBE essere aggiunto dopo una breve _descrizione_, aggiungendo ulteriori informazioni contestuali riguardo le modifiche apportate al codice. Il _corpo_ DEVE iniziare dopo una linea vuota dalla _descrizione_. 1. Un _corpo_ può contenere qualsiasi contenuto e POTREBBE essere formato da qualsiasi numero di linee separate. 1. Uno o più _pié di pagina_ POTREBBERO essere usati dopo una linea vuota dallo _spazio_. Ogni _piè di pagina_ DEVE avere una parola chiave seguita da `:` o `#`, poi seguita da un _token_ (ispirato a [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. Un _token_ DEVE usare `-` al posto degli spazi, ad esempio, `Acked-by` (questo serve a distinguere _piè di pagina_ e _corpo_). Un eccezione è fatta per `BREAKING CHANGE`, ch POTREBBE essere utilizzata come _token_. 1. Un _piè di pagina_ POTREBBE contenere spazi e linee vuote, and DEVE finire quando si incontra il _token_. 1. Una _breaking changes_ DEVE essere indicata dopo il _tipo_/_contesto_ come `!`, all'inizio delle sezioni _piè di pagina_ o del _corpo_ del commit. Una _breaking change_ DEVE essere scritta in maiuscolo `BREAKING CHANGE`, seguita dai due punti ed uno spazio. 1. Una descrizione DEVE essere aggiunta dopo il testo `BREAKING CHANGE: `, descrivendo il cambiamento delle API. Es: _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Un `!` POTREBBE essere aggiunti prima del prefisso`:` nel _tipo_/_contesto_, per attirare notificare l'introduzione di una breaking change. `BREAKING CHANGE: description` DEVE essere aggiungto nel _copro_ o _piè di pagina_ se un `!` è presente. 1. Un commit POTREBBE utilizzare altri _tipi_ al di fuori di `feat` e `fix` nel messaggio. 1. La convenzione NON DEVE tener conto del maiuscolo o minuscolo, ad eccezione di `BREAKING CHANGE` che DEVE sempre essere maiuscolo. 1. `BREAKING-CHANGE` equivale a `BREAKING CHANGE` ## Perchè utilizzare commit convenzionali * CHANGELOG generati automaticamente. * Determina automaticamente l'incremento di un versionamento semver (basandosi sui tipi di commit utilizzati). * Comunica la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate. * Attiva build e processi di rilascio. * Rendi più semplice alle persone contribuire al tuo progetto, dando la possibilità di esplorare una cronologia di commit più strutturata. ## FAQ ### Come dovrei comportarmi con i messaggi dei commit nella fase iniziale del progetto? Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente *qualcuno*, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc. ### I _tipi_ devono essere in maiuscolo o minuscoli? Si possono utilizzare entrambi, ma si raccomanda di essere consistenti ed utilizzarne solamente uno. ### Cosa faccio se il tipo di commit è conforme a più di un tipo? Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request organizzate meglio. ### Non scoraggia sviluppo ed iterazioni rapidi? Scoraggia a farlo in una maniere disorganizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori. ### Potrebbe Commit Convenzionali limitare gli sviluppatori a fare solamente alcuni tipi commit perchè penseranno nei tipi forniti dalla specifica? Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo. ### Come si collega a SemVer? I commit di tipo `fix` dovrebbero essere traducibili ai rilasci `PATCH`. I commit di tipo `feat` dovrebbero essere traducibili ai rilasci `MINOR`. I commit con `BREAKING CHANGE`, indipendentemente dal tipo, dovrebbero essere traducibili ai rilasci `MAJOR`. ### Come dovrei versionare le mie estensioni per la specifica Commit Convenzionali? (Es: `@jameswomack/conventional-commit-spec`) Raccomandiamo l'utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!) ### Cosa faccio se accidentalmente utilizzo un tipo di commit sbagliato? #### Quando usi un tipo della specifica ma non quello giusto (Es: `fix` invece di `feat`) Se ancora devi creare il merge o il rilascio dell'errore, raccomandiamo l'utilizzo di `git rebase -i` per riscrivere la cronologia dei commit. Nel caso ti abbia già rilasciato questa correzione dipende dai tool e processi che usi. #### Quando usi un tipo *non* della specifica (Es: `feet` invece di `feat`) Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica. ### Devono tutti i contributori seguire la specifica Commit Convenzionali? No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato. ================================================ FILE: content/v1.0.0/index.ja.md ================================================ --- draft: false aliases: ["/ja/"] --- # Conventional Commits 1.0.0 ## 概要 Conventional Commits の仕様はコミットメッセージのための軽量の規約です。 明示的なコミット履歴を作成するための簡単なルールを提供します。この規則に従うことで自動化ツールの導入を簡単にします。 コミットメッセージで機能追加・修正・破壊的変更などを説明することで、この規約は [SemVer](http://semver.org/lang/ja/) と協調動作します。 コミットメッセージは次のような形にする必要があります: --- 原文： ``` [optional scope]: [optional body] [optional footer(s)] ``` 訳： ``` <型>[任意 スコープ]: <タイトル> [任意 本文] [任意 フッター] ``` ---
あなたのライブラリの利用者に意図を伝えるために、コミットは以下の構造化された要素を持ちます： 1. **fix:** _型_ `fix` を持つコミットはコードベースのバグにパッチを当てます (これは Semantic Versioning における [`PATCH`](http://semver.org/#summary) に相当します)。 1. **feat:** _型_ `feat` を持つコミットはコードベースに新しい機能を追加します (これは Semantic Versioning における [`MINOR`](http://semver.org/#summary) に相当します)。 1. **BREAKING CHANGE:** _フッター_ に `BREAKING CHANGE:` が書かれているか型/スコープの直後に `!` が追加されているコミットは API の破壊的変更を導入します (Semantic Versioning における [`MAJOR`](http://semver.org/#summary) に相当します)。 `BREAKING CHANGE` は任意の _型_ のコミットに含めることができます。 1. `fix:` や `feat:` 以外の _型_ も許されています。たとえば [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (これは [Angular の規約](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) が基になっています) は `build:`, `chore:`, `ci:`,`docs:`, `style:`, `refactor:`, `perf:`, `test:`, などを推奨しています。 1. [git trailer format](https://git-scm.com/docs/git-interpret-trailers) に似た規約に従って、`BREAKING CHANGE: <タイトル>` 以外の _フッター_ が与えられるかもしれません。 追加の型たちは Conventional Commits の仕様で義務付けられているものではなく、(BREAKING CHANGE を含まない限り) Semantic Versioning に対する暗黙的な効果を持ちません。

コミットの型には追加の文脈の情報として _スコープ_ を追加することができます。スコープは括弧で囲みます。たとえば `feat(parser): add ability to parse arrays` のようになります。 ## 例 ### タイトルおよび破壊的変更のフッターを持つコミットメッセージ ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 破壊的変更を目立たせるために `!` を持つコミットメッセージ ``` feat!: send an email to the customer when a product is shipped ``` ### スコープおよび破壊的変更を目立たせるための `!` を持つコミットメッセージ ``` feat(api)!: send an email to the customer when a product is shipped ``` ### `!` と BREAKING CHANGE フッターの両方を持つコミットメッセージ ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### 本文を持たないコミットメッセージ ``` docs: correct spelling of CHANGELOG ``` ### スコープを持つコミットメッセージ ``` feat(lang): add polish language ``` ### 複数段落からなる本文と複数のフッターを持ったコミットメッセージ ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## 仕様 この文書におけるキーワード「しなければならない (MUST)」「してはならない (MUST NOT)」「要求されている (REQUIRED)」「することになる (SHALL)」「することはない(SHALL NOT)」「する必要がある (SHOULD)」「しないほうがよい (SHOULD NOT)」「推奨される (RECOMMENDED)」「してもよい (MAY)」「選択できる (OPTIONAL)」は [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) ([JPNIC 日本語訳](https://www.nic.ad.jp/ja/tech/ipa/RFC2119JA.html)) で述べられているように解釈されるべきものです。 1. コミットは `feat` や `fix` などの型から始まり (MUST)、その後ろにはスコープ (OPTIONAL) と `!` (OPTIONAL) が続き、その後ろにコロンとスペース (REQUIRED) が続く。 1. コミットがあなたのアプリケーションやライブラリに新しい機能を追加するとき、型 `feat` が使われなければならない (MUST)。 1. コミットがあなたのアプリケーションのためのバグ修正を行うとき、型 `fix` が使われなければならない (MUST)。 1. スコープを型の後ろに記述してもよい (MAY)。スコープは、コードベースのセクションを記述する括弧で囲まれた名詞にしなければならない (MUST)。例: `fix(parser):`。 1. 型/スコープの後ろのコロンとスペースの直後にタイトルが続かなければならない (MUST)。 タイトルはコード変更の短かい要約である。例: `fix: array parsing issue when multiple spaces were contained in string`。 1. 短いタイトルの後ろにより長いコミットの本文を追加してもよい (MAY)。これはコード変更に関する追加の情報を提供する。 本文はタイトルの下の 1 行の空行から始めなければならない (MUST)。 1. コミットの本文は自由な形式であり、改行で区切られた複数の段落で構成することができる (MAY)。 1. ひとつ以上のフッターを、本文の下の 1 行の空行に続けて書くことができる (MAY)。 それぞれのフッターは、ひとつの単語トークン、それに続く `:` か `#` によるセパレータ、そして文字列の値から構成されなければならない (MUST) (これは [git trailer convention](https://git-scm.com/docs/git-interpret-trailers) に触発されている)。 1. フッターのトークンは空白の代わりに `-` を使わなければならない (MUST)。例えば `Acked-by` とする (これは複数段落からなる本文からフッターを区別するのに役立つ)。 例外として `BREAKING CHANGE` があり、これをトークンとして使用することができる (MAY)。 1. フッターの値にはスペースと改行を含めることができる (MAY)。そして次のフッターのトークンとセパレータの組が見つかった時、以前のフッターのパースは終了しなければならない (MUST)。 1. 破壊的変更は、コミットの型/スコープの接頭辞か、フッターによって明示されなければならない (MUST)。 1. 破壊的変更がフッターとして含まれる場合は、大文字の BREAKING CHANGE の後ろにコロンとスペース、そしてタイトルを続けなければならない (MUST)。例: `BREAKING CHANGE: environment variables now take precedence over config files`。 1. 破壊的変更が型/スコープの接頭辞として含まれる場合は、`:` の直前に `!` を用いて明示されねばならない (MUST)。`!` が使用された場合には、 フッターから `BREAKING CHANGE:` を省略してもよい (MAY)。その場合はコミットのタイトル部分で破壊的変更の内容を説明することになる (SHALL)。 1. `feat` と `fix` 以外の型を使うことができる (MAY)。例: `docs: updated ref docs.`。 1. Conventional Commits を構成する情報の単位は、大文字の `BREAKING CHANGE` を除いて、実装は大文字と小文字を区別してはならない (MUST NOT)。 1. フッターのトークンにおいて BREAKING-CHANGE は BREAKING CHANGE と同じトークンとして解釈されなければならない (MUST)。 ## 何故 Conventional Commits を使うのか * 変更履歴 (CHANGELOG) を自動的に生成できます。 * semantic version 単位で自動的に履歴をまとめられます (コミットの型に基づきます)。 * チームメイトや一般のユーザー、およびその他の利害関係者へ変更の内容を伝えることができます。 * ビルドや公開の処理をトリガーできます。 * より構造化されたコミット履歴を調査できるようにすることで、人々があなたのプロジェクトに貢献しやすくなります。 ## よくある質問 ### 初期の開発段階ではコミットメッセージをどのように扱うべきですか？ すでに製品をリリースしているかのように進めることをお勧めします。 あなたの仲間のソフトウェア開発者であっても、普通は *誰か* があなたのソフトウェアを使っています。 何が修正されたのかや何が壊れたのかなどを彼らは知りたいでしょう。 ### コミットタイトル (1 行目) の型は大文字か小文字のどちらがよいですか？ どちらでも問題はありませんが、一貫性を保つべきです。 ### コミットが複数のコミット型からなるような場合はどうすればよいですか？ 可能な限り、引き返して複数のコミットに分割します。 Conventional Commits の利点のひとつは、より組織化されたコミットとプルリクエストを行う事を可能にする事です。 ### これは開発速度とインテグレーションを遅くしたりはしませんか？ 無秩序にただ早く開発することはお勧めではありません。 これはあなたがさまざまな貢献者との複数のプロジェクト間で長期的に素早く動けるようにするのを助けます。 ### Conventional Commits では開発者は与えられた型の中で考える必要があるため、作ることのできるコミットの種類が制限されてしまうのではありませんか？ Conventional Commits は `fix` などの特定の型を持つコミットを作るように促します。 それ以外には、Conventional Commits の柔軟性は、あなたのチームが独自の型を提案し作り、また時間の経過とともにそれらの型を変更していくことを許します。 ### これは SemVer とどのような関係を持っていますか？ `fix` 型のコミットは `PATCH` リリースへ変換されます。`feat` 型のコミットは `MINOR` リリースへ変換されます。型にかかわらずコミット内で `BREAKING CHANGE` を使ったコミットは `MAJOR` リリースに変換されるべきでしょう。 ### Conventional Commits の仕様についての私の拡張はどのようにバージョンを振るべきでしょうか？ 例: `@jameswomack/conventional-commit-spec` SemVer を使用して、この仕様に対する独自の拡張をリリースすることをお勧めします (そしてそのような拡張仕様の作成を推奨します！)。 ### 間違ったコミット型を使用してしまった時はどうしたらいいですか？ #### 仕様的に正しい型だが意味的に間違った型を使用した場合、たとえば `feat` の代わりに `fix` 間違いをマージやリリースする前に、`git rebase -i` を使ってコミット履歴を編集することをお勧めします。 リリース後であれば、どのようなツールやプロセスを使用しているかによって後始末は異なってくるでしょう。 #### 仕様に *ない* 型を使った場合、例えば `feat` ではなく `feet` 最悪のシナリオはコミットが Conventional Commits の仕様を満たさない場合です。しかしそれは世界の終わりではありません。 それは単に仕様に基づいているツールによってコミットが見逃されるだけでしかありません。 ### 貢献者全員が Conventional Commits の仕様を使用する必要がありますか？ いいえ！ Git で squash ベースのワークフローを使用する場合は、主要メンテナがマージ時にコミットメッセージをクリーンアップすることができるため、臨時のコミッタには作業負荷がかかりません。 また、これをするための一般的な方法としては、プルリクエストからのコミットを git システムが自動的に squash し、主要メンテナによるマージ時に適切な git コミットメッセージを入力するためのフォームを表示するというものです。 ### Conventional Commits は `revert` コミットをどのように扱いますか？ コードを revert するのは複雑な場合があります。 複数のコミットを revert しますか？ 機能を revert するとき、次のリリースはただのパッチでしょうか？ Conventional Commits は revert の振る舞いを定義するための明示的な努力をしません。 その代わりに、revert を処理するためのロジックを型とフッターの柔軟性を利用して開発するようなツールの作者に、これを任せます。 我々のおすすめの方法としては、ひとつは `revert` 型と revert されるコミットの SHA を参照するフッターを使うようにすることです。 ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.ko.md ================================================ --- draft: false aliases: ["/ko/"] --- # Conventional Commits 1.0.0 ## 개요 Conventional Commits 스펙은 커밋 메시지에 곁들여진 가벼운 컨벤션으로 명확한 커밋 히스토리를 생성하기 위한 간단한 규칙을 제공합니다. 이렇게 만들어진 커밋 히스토리를 이용하여 더 쉽게 자동화된 도구를 만들 수 있습니다. 이 컨벤션은 커밋 메시지에 신규 기능 추가, 문제 수정, 커다란 변화가 있음을 기술함으로써 [유의적 버전(Sementic Versioning)](https://semver.org/lang/ko/)과 일맥상통한 면이 있습니다. 커밋 메시지는 다음과 같은 구조가 되어야 합니다: --- ``` <타입>[적용 범위(선택 사항)]: <설명> [본문(선택 사항)] [꼬리말(선택 사항)] ``` ---
커밋에는 라이브러리를 사용하는 사람들에게 의도를 전달하기 위해 다음과 같은 구조적 요소가 포함되어 있습니다. 1. **fix:** 코드베이스에서 버그를 패치하는 `fix` _타입_ 의 커밋 (이는 유의적 버전에서의 [`PATCH`](http://semver.org/#summary)와 관련이 있습니다). 1. **feat:** 코드베이스에서 새 기능이 추가되는 `feat` _타입_ 의 커밋 (이는 유의적 버전에서의 [`MINOR`](http://semver.org/#summary)와 관련이 있습니다). 1. **BREAKING CHANGE:** `BREAKING CHANGE:`이라는 꼬리말을 가지거나 타입/스코프 뒤에 !문자열을 붙인 커밋은 단절적 API 변경(breaking API change)이 있다는 것을 의미합니다 (이는 유의적 버전에서의 [`MAJOR`](http://semver.org/#summary)와 관련이 있습니다). 어떤 커밋 타입이라도 BREAKING CHANGE는 해당 커밋의 일부가 될 수 있습니다. 1. `fix:`와 `feat:` 이외의 다른 _타입_ 도 허용됩니다. 예를 들어 [앵귤러 컨벤션](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)을 기반으로 하는 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)에서는 `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` 등의 타입을 사용할 것을 권고하고 있습니다. 1. `BREAKING CHANGE:` 이외의 _꼬리말_ 을 규정 할 수 있으며 다음과 비슷한 컨벤션을 따를 수 있습니다. [git trailer format](https://git-scm.com/docs/git-interpret-trailers). 추가 타입들은 컨벤션 커밋 규격에 의해 의무화되지 않으며, 유의적 버전에 잠재적인 영향을 주지 않습니다(그것이 BREAKING CHANGE를 포함하지 않는 한).

추가적인 문맥 정보를 제공하기 위한 목적으로 사용되는 적용 범위는 커밋의 타입에 덧붙여질 수 있는데 괄호 안에 포함됩니다, 예를 들면, `feat(parser): add ability to parse arrays`.
## 예제 ### 설명과 BREAKING CHANGE 꼬리말을 가지는 커밋 메시지 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 단절적 변경(breaking change)에 주의를 주기 위해 `!`를 포함한 커밋 메시지 ``` feat!: send an email to the customer when a product is shipped ``` ### 단절적 변경(breaking change)에 주의를 주기 위해 적용 범위와 `!` 를 포함한 커밋 메시지 ``` feat(api)!: send an email to the customer when a product is shipped ``` ### BREAKING CHANGE 꼬리말과 `!`를 함께 포함한 커밋 메시지 ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### 본문이 없는 커밋 메시지 ``` docs: correct spelling of CHANGELOG ``` ### 적용 범위를 가지는 커밋 메시지 ``` feat(lang): add polish language ``` ### 다중-단락 본문과 다수의 꼬리말을 가진 커밋 메시지 ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## 규격 이 문서에서 언급되는 주요 단어들인 “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, 그리고 “OPTIONAL”는 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)에 기술된 그대로 해석해야 합니다. 1. 모든 커밋은 `feat`, `fix` 같은 명사로 된 접두어를 포함해야 하고 그 뒤로 선택 사항인 적용 범위, 선택 사항인 `!`, 그리고 필수인 `:`과 공백이 있어야 합니다. 1. `feat` 타입은 커밋에 애플리케이션이나 라이브러리에 새로운 기능이 추가될 때 사용되어야 합니다. 1. `fix` 타입은 커밋에 애플리케이션의 버그 수정을 하는 내용을 포함하는 경우에 사용되어야 합니다. 1. 적용 범위는 타입 다음에 기술하는데 이는 코드베이스가 적용되는 영역을 기술하는 명사로 괄호로 감싸져야 합니다, 예를 들어, `fix(parser):` 1. 설명은 타입/적용 범위 접두어 뒤에 있는 콜론(:)과 공백 다음에 작성되어야 합니다. 설명은 코드 변경 사항에 대한 짧은 요약입니다, 예를 들어, _fix: array parsing issue when multiple spaces were contained in string._ 1. 더 긴 커밋 본문은 짧은 설명 다음에 위치할 수 있으며 코드 변경 사항에 대한 추가적인 문맥적인 정보를 제공합니다. 본문은 반드시 설명 다음에 빈 행으로 시작해야 합니다. 1. 커밋 본문은 형식이 자유로우며 새 줄로 분리된 많은 수의 단락들로 구성 될 수 있습니다. 1. 하나 또는 다수의 꼬리말들은 본문 다음 빈 행 다음에 위치합니다. 각각의 꼬리말은 반드시 단어 토큰, 그 뒤에 `:` 또는 `#` 구분자, 그 뒤에 문자열 값으로 구성되어야 합니다(이것은 다음에 영향을 받았습니다 [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. 꼬리말의 토큰은 반드시 공백 문자 대신 `-` 를 사용해야 합니다. 예를 들면 `Acked-by` (이것은 다중-단락 본문과 꼬리말 섹션을 구분하는데 도움이 됩니다). `BREAKING CHANGE`는 예외적으로 토큰으로 사용될 수 있습니다. 1. 꼬리말의 값은 공백이나 새 줄들을 포함할 수 있으며, 구문 분석기는 다음의 유효한 꼬리말 토큰/구분자 쌍을 관찰하면 반드시 종료해야 합니다. 1. 단절적 변경은 반드시 커밋의 타입/적용범위 접두어에 표시하거나 꼬리말에 기입되어야 합니다. 1. 꼬리말로 포함된 경우 단절적 변경은 반드시 대문자 문자열 BREAKING CHANGE과 뒤따르는 콜론(:), 공백, 그리고 설명으로 구성되어야 합니다. 예를 들면 _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 타입/범위 접두어에 포함된 경우, 단절적 변경은 반드시 `:` 바로 앞의 `!` 를 명시해야 합니다. 만약 `!` 가 사용되면, `BREAKING CHANGE:` 는 꼬리말 섹션에서 생략할 수 있으며, 커밋 설명은 단절적 변경을 설명하기 위해 사용되어야 합니다. 1. `feat`와 `fix` 이외의 타입이 커밋 메시지에 사용될 수 있습니다. 예: _docs: updated ref docs._ 1. Conventional Commit을 구성하는 정보의 단위는 반드시 대문자여야 하는 BREAKING CHANGES를 제외하고 구현자에 의해 대소문자를 구분하는 것으로 처리되어서는 안됩니다. 1. BREAKING-CHANGE는 꼬리말에서 토큰으로 사용될 때 반드시 BREAKING CHANGE와 동의어야 합니다. ## 왜 Conventional Commits를 사용할까요? * CHANGELOG를 자동으로 생성하기 위해서 * (포함된 커밋의 타입에 기반하여) 유의적 버전을 자동으로 변경하기 위해서 * 팀 동료, 타인, 그리고 기타 이해당사자에게 변화의 본질을 전달하기 위해서 * 빌드와 배포 프로세스를 수행하기 위해서 * 더 구조화된 커밋 히스토리를 보여줘서 사람들이 프로젝트에 기여하기 더 쉽도록 하기 위해서 ## FAQ ### 초기 개발 단계에서 커밋 메시지를 어떻게 다루어야 하나요? 제품을 이미 출시한 것처럼 진행하세요. 일반적으로 *누군가* 는 여러분의 소프트웨어를 사용하고 있는데 그게 동료 개발자일 수도 있고 그들은 무엇이 고쳐졌는지, 무엇이 문제인지 등을 알고 싶어 할 것입니다. ### 커밋 제목에서 타입은 대문자로 쓰나요 소문자로 쓰나요? 대소문자 구분은 없지만 일관되게 사용하는 것이 좋습니다. ### 커밋이 커밋 타입 중 하나 이상에 해당하는 경우 어떻게 해야 하나요? 가능하면 돌아가서 여러 개의 커밋으로 쪼개세요. Conventional Commits의 이점 중 하나는 우리가 보다 조직화된 커밋과 PR을 만들도록 유도하는 능력입니다. ### Conventional Commits가 빠른 개발과 빠른 반복을 방해하지 않나요? Conventional Commits는 무질서한 방법으로 빨리 움직이는 것을 지양하고 다양한 기여자들을 가진 여러 프로젝트에서 장기적으로 빠르게 이동할 수 있도록 도와줍니다. ### Conventional Commits가 개발자들로 하여금 제공된 타입 안에서 생각하게 되기 때문에 그들이 만든 커밋의 타입을 제한하도록 유도할 수 있을까요? Conventional Commits는 fix 같은 특정 종류의 커밋 타입을 더 많이 만들도록 장려하고 있습니다. 그 외에도, Conventional Commits의 유연성은 여러분의 팀이 그들만의 타입을 고안하고 시간이 지남에 따라 그 타입을 바꿀 수 있게 해줍니다. ### 이것이 SemVer와 어떤 관련이 있나요? `fix` 타입의 커밋은 `PATCH` 버전으로 번역해야 합니다. `feat` 형식 커밋은 `MINOR` 버전으로 번역해야 합니다. 타입과 관계없이 `BREAKING CHANGE`를 포함한 커밋은 `MAJOR`로 번역해야 합니다. ### Conventional Commit 스펙을 개인적으로 확장한 형태의 버전을 어떻게 사용할 수 있을까요? 예를 들어, `@jameswomack/conventional-commit-spec` SemVer를 사용해서 이 규격에 대한 사용자 자신의 확장판을 릴리즈할 것을 추천합니다. (그리고 이러한 확장판을 만드는 것을 권장합니다!) ### 실수로 잘못된 커밋 타입을 사용하면 어떻게 해야 하나요? #### 스펙에 맞는 타입을 사용하고 있지만 올바른 타입이 아닌 경우, 예를 들어, `feat` 대신 `fix` 실수를 병합 또는 리베이스하기 전에, `git rebase -i`를 사용하여 커밋 히스토리를 편집할 것을 권장합니다. 릴리즈 후에는 사용하는 툴과 프로세스에 따라 정리하는 방법이 다를 수 있습니다. #### 스펙에 맞지 않은 타입을 사용하는 경우, 예를 들어, `feat` 대신 `feet` 최악의 경우, Conventional Commmit 규격을 충족하지 않는 커밋이 추가되었다고 해서 그것이 세계의 종말을 의미하지 않습니다. 이는 커밋이 단순히 규격을 기반으로 하는 툴에 의해 누락된다는 것을 의미합니다. ### 모든 기여자가 Conventional Commit 규격을 사용해야 하나요? 아니요! Git을 기반으로 스쿼시를 사용하는 경우, 리드 유지관리자는 커밋된 메시지를 병합할 때 정리할 수 있으므로 일반 커밋자에 작업량이 추가되지 않습니다. 이에 대한 일반적인 작업 흐름은 Git 시스템이 자동으로 풀 요청에서 커밋되도록 하고 리드 유지관리자가 병합에 대한 적절한 Git 커밋 메시지를 입력할 수 있는 양식을 제시하도록 하는 것입니다. ### Conventional Commits은 revert commits을 어떻게 다루어야 하나요? 코드를 되돌리는 것은 복잡해질 수 있습니다: 여러 개의 커밋을 되돌리고 있는가요? 기능을 되돌리는 경우 패치가 아니라 다음 릴리즈여야 하는가요? Conventional Commits는 되돌리기 행동을 정의하기 위해 명확한 작업을 하지 않습니다. 툴 개발자에게 되돌리기를 다루는 로직 개발에 _타입_ 과 _꼬리말_ 의 유연함을 사용하도록 맡길 것입니다. 한 가지 권장 사항은 `revert` 타입과 되돌려지는 커밋들의 SHA들을 참조하는 꼬리말를 사용하는 것입니다: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.md ================================================ --- draft: false aliases: ["/en/"] --- # Conventional Commits 1.0.0 ## Summary The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](http://semver.org), by describing the features, fixes, and breaking changes made in commit messages. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in Semantic Versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in Semantic Versioning). 1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in Semantic Versioning). A BREAKING CHANGE can be part of commits of any _type_. 1. _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. 1. _footers_ other than `BREAKING CHANGE: ` may be provided and follow a convention similar to [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE).

A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`. ## Examples ### Commit message with description and breaking change footer ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit message with `!` to draw attention to breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### Commit message with scope and `!` to draw attention to breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit message with both `!` and BREAKING CHANGE footer ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit message with no body ``` docs: correct spelling of CHANGELOG ``` ### Commit message with scope ``` feat(lang): add Polish language ``` ### Commit message with multi-paragraph body and multiple footers ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by the OPTIONAL scope, OPTIONAL `!`, and REQUIRED terminal colon and space. 1. The type `feat` MUST be used when a commit adds a new feature to your application or library. 1. The type `fix` MUST be used when a commit represents a bug fix for your application. 1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., `fix(parser):` 1. A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string_. 1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. 1. A commit body is free-form and MAY consist of any number of newline separated paragraphs. 1. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a `:` or `#` separator, followed by a string value (this is inspired by the [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE`, which MAY also be used as a token. 1. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed. 1. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer. 1. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., _BREAKING CHANGE: environment variables now take precedence over config files_. 1. If included in the type/scope prefix, breaking changes MUST be indicated by a `!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change. 1. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: update ref docs._ 1. The units of information that make up Conventional Commits MUST NOT be treated as case-sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase. 1. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've already released the product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### Are the types in the commit title uppercase or lowercase? Any casing may be used, but it's best to be consistent. ### What do I do if the commit conforms to more than one of the commit types? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the Conventional Commits specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the Conventional Commits specification? No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ### How does Conventional Commits handle revert commits? Reverting code can be complicated: are you reverting multiple commits? if you revert a feature, should the next release instead be a patch? Conventional Commits does not make an explicit effort to define revert behavior. Instead we leave it to tooling authors to use the flexibility of _types_ and _footers_ to develop their logic for handling reverts. One recommendation is to use the `revert` type, and a footer that references the commit SHAs that are being reverted: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.ml.md ================================================ --- draft: false aliases: ["/ml/"] --- # പരമ്പരാഗത കമ്മിറ്റുകൾ 1.0.0 ## സംഗ്രഹം കമ്മിറ്റ് സന്ദേശങ്ങൾക്ക് മുകളിലുള്ള ഒരു ഭാരം കുറഞ്ഞ കൺവെൻഷനാണ് കൺവെൻഷണൽ കമ്മിറ്റ്സ് സ്പെസിഫിക്കേഷൻ. വ്യക്തമായ പ്രതിബദ്ധതയുള്ള ചരിത്രം സൃഷ്‌ടിക്കുന്നതിന് ഇത് എളുപ്പമുള്ള ഒരു കൂട്ടം നിയമങ്ങൾ നൽകുന്നു; ഇത് മുകളിൽ ഓട്ടോമേറ്റഡ് ടൂളുകൾ എഴുതുന്നത് എളുപ്പമാക്കുന്നു. ഈ കൺവെൻഷൻ [SemVer](http://semver.org), കമ്മിറ്റ് സന്ദേശങ്ങളിൽ വരുത്തിയ സവിശേഷതകൾ, പരിഹാരങ്ങൾ, ബ്രേക്കിംഗ് മാറ്റങ്ങൾ എന്നിവ വിവരിച്ചുകൊണ്ട്. പ്രതിബദ്ധത സന്ദേശം ഇനിപ്പറയുന്ന രീതിയിൽ ക്രമീകരിക്കണം: --- ``` [ഓപ്ഷണൽ സ്കോപ്പ്]: <വിവരണം> [ഓപ്ഷണൽ ബോഡി] [ഓപ്ഷണൽ അടിക്കുറിപ്പ്(കൾ)] ``` ---
കമ്മിറ്റിൽ ഇനിപ്പറയുന്ന ഘടനാപരമായ ഘടകങ്ങൾ അടങ്ങിയിരിക്കുന്നു, ഉദ്ദേശ്യം ആശയവിനിമയം നടത്തുന്നതിന് നിങ്ങളുടെ ലൈബ്രറിയുടെ ഉപഭോക്താക്കൾ: 1. ** പരിഹരിക്കുക:** നിങ്ങളുടെ കോഡ്‌ബേസിലെ ഒരു ബഗ് പാച്ചുചെയ്യുന്ന _type_ `fix` (ഇത് സെമാന്റിക് പതിപ്പിംഗിലെ [`PATCH`](http://semver.org/#summary) മായി ബന്ധപ്പെട്ടിരിക്കുന്നു). 1. **feat:** _type_ `feat` ന്റെ ഒരു പ്രതിബദ്ധത കോഡ്ബേസിലേക്ക് ഒരു പുതിയ സവിശേഷത അവതരിപ്പിക്കുന്നു (ഇത് സെമാന്റിക് വേർഷനിംഗിലെ [`MINOR`](http://semver.org/#summary) എന്നതുമായി ബന്ധപ്പെട്ടിരിക്കുന്നു). 1. **ബ്രേക്കിംഗ് മാറ്റം:** 'BREAKING CHANGE:' എന്ന അടിക്കുറിപ്പുള്ള ഒരു പ്രതിബദ്ധത, അല്ലെങ്കിൽ തരം/സ്കോപ്പിന് ശേഷം `!` ചേർക്കുക, ഒരു ബ്രേക്കിംഗ് API മാറ്റം അവതരിപ്പിക്കുന്നു ([`MAJOR`](http:/ /semver.org/#summary) സെമാന്റിക് പതിപ്പിൽ). ഒരു ബ്രേക്കിംഗ് മാറ്റം ഏത് _തരം 1. `fix:`, `feat:` എന്നിവ ഒഴികെയുള്ള _types_ അനുവദനീയമാണ്, ഉദാഹരണത്തിന് [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) ([കോണീയ കൺവെൻഷൻ](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) ശുപാർശ ചെയ്യുന്നത് `build:`, `chore: `, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` എന്നിവയും മറ്റുള്ളവയും. 1. `BREAKING CHANGE: ` ഒഴികെയുള്ള _footers_ നൽകുകയും സമാനമായ ഒരു കൺവെൻഷൻ പിന്തുടരുകയും ചെയ്യാം [git ട്രെയിലർ ഫോർമാറ്റ്](https://git-scm.com/docs/git-interpret-trailers). അധിക തരങ്ങൾ കൺവെൻഷണൽ കമ്മിറ്റ് സ്‌പെസിഫിക്കേഷൻ നിർബന്ധമാക്കിയിട്ടില്ല, കൂടാതെ സെമാന്റിക് വേർഷനിംഗിൽ (അവയിൽ ഒരു ബ്രേക്കിംഗ് മാറ്റം ഉൾപ്പെടുത്തിയില്ലെങ്കിൽ) പ്രത്യക്ഷമായ ഫലമൊന്നുമില്ല.

കൂടുതൽ സാന്ദർഭിക വിവരങ്ങൾ നൽകുന്നതിന് ഒരു കമ്മിറ്റിന്റെ തരത്തിന് ഒരു സ്കോപ്പ് നൽകാം, അത് പരാൻതീസിസിൽ അടങ്ങിയിരിക്കുന്നു, ഉദാ., `ഫീറ്റ്(പാഴ്സർ): അറേകൾ പാഴ്‌സ് ചെയ്യാനുള്ള കഴിവ് ചേർക്കുക`. ## ഉദാഹരണങ്ങൾ ### വിവരണവും ബ്രേക്കിംഗ് മാറ്റ ഫൂട്ടറും സഹിതമുള്ള കമ്മിറ്റ് സന്ദേശം ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### മാറ്റത്തെ തകർക്കുന്നതിലേക്ക് ശ്രദ്ധ ആകർഷിക്കാൻ `!` എന്ന സന്ദേശം നൽകൂ ``` feat!: send an email to the customer when a product is shipped ``` ### വ്യാപ്തിയുള്ള സന്ദേശം കമ്മിറ്റ് ചെയ്‌ത് മാറ്റത്തിലേക്ക് ശ്രദ്ധ ആകർഷിക്കാൻ `!` ``` feat(api)!: send an email to the customer when a product is shipped ``` ### `!` എന്നതും ബ്രേക്കിംഗ് മാറ്റുക അടിക്കുറിപ്പും ഉപയോഗിച്ച് കമ്മിറ്റ് സന്ദേശം ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### ശരീരമില്ലാതെ കമ്മിറ്റ് സന്ദേശം ``` docs: correct spelling of CHANGELOG ``` ### സ്കോപ്പുള്ള സന്ദേശം കമ്മിറ്റ് ചെയ്യുക ``` feat(lang): add polish language ``` ### മൾട്ടി-പാരഗ്രാഫ് ബോഡിയും ഒന്നിലധികം ഫൂട്ടറുകളും ഉള്ള കമ്മിറ്റ് സന്ദേശം ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specification "നിർബന്ധം"(“MUST”), "ആവശ്യമില്ല" (“MUST NOT”), "ആവശ്യമുള്ളത്" (“REQUIRED”), "ചെയ്യും" (“SHALL”), "ചെയില്ല"(“SHALL NOT”), "വേണം" (“SHOULD”), "ചെയ്യരുത്" (“SHOULD NOT”), "ശുപാർശ ചെയ്യുന്നു" (“RECOMMENDS”), ഒരുപക്ഷേ ("MAY"), "ഓപ്ഷണൽ" (“OPTIONAL”)എന്നീ പ്രധാന വാക്കുകൾ ഈ പ്രമാണത്തിൽ വിവരിച്ചിരിക്കുന്നതുപോലെ വ്യാഖ്യാനിക്കേണ്ടതാണ് [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. കമ്മിറ്റുകൾ ഒരു നാമം, `feat`,` ഫിക്സ്` മുതലായവ അടങ്ങുന്ന ഒരു തരം പ്രിഫിക്‌സിൽ ആരംഭിക്കണം, തുടർന്ന് ഓപ്‌ഷണൽ സ്കോപ്പ്, `!` ഓപ്‌ഷണൽ, ഒരു കോളനും ആവശ്യമായ സ്‌പെയ്‌സും. 2. ഒരു കമ്മിറ്റ് ആപ്ലിക്കേഷനിലേക്കോ ലൈബ്രറിയിലേക്കോ പുതിയ പ്രവർത്തനം ചേർക്കുമ്പോൾ `feat` തരം ഉപയോഗിക്കണം. 3. കമ്മിറ്റ് ആപ്ലിക്കേഷൻ കോഡിലെ (ബഗ്) ഒരു പിശകിന്റെ തിരുത്തലിനെ പ്രതിനിധീകരിക്കുമ്പോൾ `fix` തരം ഉപയോഗിക്കണം. 4. ഒരു തരത്തിന് ശേഷം ഒരു സ്കോപ്പ് ചേർക്കാം. ഒരു സ്കോപ്പിൽ പരാൻതീസിസിൽ ഉൾപ്പെടുത്തിയിരിക്കുന്ന കോഡ് ബേസിന്റെ ഒരു വിഭാഗത്തെ വിവരിക്കുന്ന ഒരു നാമം അടങ്ങിയിരിക്കണം, ഉദാ, `fix(parser):`. 5. ഒരു വിവരണം ഉടൻ തന്നെ ടൈപ്പ് / സ്കോപ്പ് പ്രിഫിക്‌സിന്റെ അർദ്ധവിരാമവും സ്ഥലവും പിന്തുടരേണ്ടതാണ്. കോഡിൽ വരുത്തിയ മാറ്റങ്ങളുടെ ഒരു ഹ്രസ്വ സംഗ്രഹമാണ് വിവരണം, ഉദാ, _fix: string-ൽ ഒന്നിലധികം സ്‌പെയ്‌സുകൾ ഉള്ളപ്പോൾ അറേ പാഴ്‌സിംഗ് പ്രശ്‌നം._. 6. കോഡ് മാറ്റങ്ങളെക്കുറിച്ചുള്ള കൂടുതൽ സാന്ദർഭിക വിവരങ്ങൾ നൽകിക്കൊണ്ട് ഹ്രസ്വ വിവരണത്തിന് ശേഷം ദൈർഘ്യമേറിയ പ്രതിബദ്ധതയുള്ള ബോഡി ചേർക്കാവുന്നതാണ്. വിവരണത്തിന് ശേഷം ഒരു ശൂന്യമായ വരയ്ക്ക് ശേഷം ബോഡി ആരംഭിക്കണം. 7. ഒരു കമ്മിറ്റ് ബോഡി ഒരു സ്വതന്ത്ര രൂപമാണ്, കൂടാതെ ഒരു പുതിയ വരിയാൽ വേർതിരിക്കുന്ന എത്ര ഖണ്ഡികകളും അടങ്ങിയിരിക്കാം. 8. ഒന്നോ അതിലധികമോ അടിക്കുറിപ്പുകൾ ബോഡിക്ക് ശേഷം ഒരു ശൂന്യമായ വരി ചേർക്കാം. ഓരോ അടിക്കുറിപ്പിലും ഒരു ടോക്കൺ വാക്ക് ഉണ്ടായിരിക്കണം, അതിന് ശേഷം `: ` അല്ലെങ്കിൽ ` #` സെപ്പറേറ്റർ, തുടർന്ന് ഒരു സ്ട്രിംഗ് മൂല്യം (ഇത് [git ട്രെയിലർ കൺവെൻഷൻ] (https://git) പ്രചോദിപ്പിച്ചതാണ് -scm.com/docs/git-interpret-trailers)). 9. ഒരു അടിക്കുറിപ്പ് ടോക്കൺ വാക്ക് വൈറ്റ്‌സ്‌പേസ് പ്രതീകങ്ങൾക്ക് പകരം `-` ഉപയോഗിക്കണം, ഉദാ,`Acked-by` (ഒരു മൾട്ടി-പാരഗ്രാഫ് ബോഡിയിൽ നിന്ന് അടിക്കുറിപ്പ് വിഭാഗത്തെ വേർതിരിക്കാൻ ഇത് സഹായിക്കുന്നു) . `BREAKING CHANGE` എന്നതിനായി ഒരു അപവാദം ഉണ്ടാക്കിയിരിക്കുന്നു, അത് ഒരു ടോക്കൺ പദമായും ഉപയോഗിക്കാം. 10. ഒരു അടിക്കുറിപ്പിൽ സ്‌പെയ്‌സുകളും ബ്ലാങ്ക് ലൈനുകളും അടങ്ങിയിരിക്കാം, അടുത്ത സെപ്പറേറ്റർ / ടാബ് നിരീക്ഷിക്കുമ്പോൾ പാഴ്‌സിംഗ് അവസാനിക്കണം. 11. ബ്രേക്ക് മാറ്റങ്ങൾ ഒരു കമ്മിറ്റിന്റെ തരം/സ്കോപ്പ് പ്രിഫിക്‌സിലോ അടിക്കുറിപ്പിലെ എൻട്രിയായോ സൂചിപ്പിക്കണം. 12. ഒരു അടിക്കുറിപ്പായി ഉൾപ്പെടുത്തിയാൽ, ബ്രേക്ക് മാറ്റത്തിൽ വലിയക്ഷര വാചകം BREAKING CHANGE ഉണ്ടായിരിക്കണം, തുടർന്ന് ഒരു കോളനും ഒരു വിവരണവും, ഉദാ, _BREAKING CHANGE: എൻവയോൺമെന്റ് വേരിയബിളുകൾ ഇപ്പോൾ കോൺഫിഗറേഷൻ ഫയലുകളേക്കാൾ മുൻഗണന നൽകുന്നു_. 13. തരം / സ്കോപ്പ് പ്രിഫിക്സിൽ ഉൾപ്പെടുത്തിയിട്ടുണ്ടെങ്കിൽ, ബ്രേക്ക് മാറ്റങ്ങൾ `:` എന്നതിന് തൊട്ടുപിന്നാലെ ഒരു `!` കൊണ്ട് സൂചിപ്പിക്കണം. `!` ഉപയോഗിക്കുകയാണെങ്കിൽ, `BREAKING CHANGE:` അടിക്കുറിപ്പ് വിഭാഗത്തിൽ നിന്ന് ഒഴിവാക്കിയേക്കാം, കൂടാതെ ബ്രേക്ക് മാറ്റത്തെ വിവരിക്കാൻ പ്രതിബദ്ധത വിവരണം ഉപയോഗിക്കണം. 14. കമ്മിറ്റ് സന്ദേശങ്ങളിൽ `feat`,`fix` എന്നിവ ഒഴികെയുള്ള തരങ്ങൾ ഉപയോഗിക്കാം, ഉദാ _docs: updated ref docs._. 15. കൺവെൻഷണൽ കമ്മിറ്റുകൾ ഉണ്ടാക്കുന്ന ഇൻഫർമേഷൻ യൂണിറ്റുകളെ കേസ് സെൻസിറ്റീവ് ഇംപ്ലിമെന്ററുകളായി കണക്കാക്കരുത്, ബ്രേക്കിംഗ് ചേഞ്ച് ഒഴികെ, അത് വലിയക്ഷരത്തിലായിരിക്കണം. 16. ഒരു അടിക്കുറിപ്പിൽ ഉപയോഗിക്കുമ്പോൾ BREAKING CHANGE എന്നത് BREAKING-CHANGE MUST എന്നതിന്റെ പര്യായമായിരിക്കണം. ## എന്തിനാണ് പരമ്പരാഗത കമ്മിറ്റുകൾ ഉപയോഗിക്കുന്നത്? * സ്വയമേവ മാറ്റങ്ങൾ സൃഷ്ടിക്കുന്നു. * സ്വയമേവ ഒരു സെമാന്റിക് പതിപ്പ് ബമ്പ് നിർണ്ണയിക്കുന്നു (കമ്മിറ്റുകളുടെ തരങ്ങളെ അടിസ്ഥാനമാക്കി). * ടീമംഗങ്ങളോടും പൊതുജനങ്ങളോടും മറ്റ് പങ്കാളികളോടും മാറ്റങ്ങളുടെ സ്വഭാവം ആശയവിനിമയം നടത്തുക. * ബിൽഡ്, പ്രസിദ്ധീകരണ പ്രക്രിയകൾ ട്രിഗർ ചെയ്യുന്നു. * പര്യവേക്ഷണം ചെയ്യാൻ ആളുകളെ അനുവദിച്ചുകൊണ്ട് നിങ്ങളുടെ പ്രോജക്‌ടുകളിലേക്ക് സംഭാവന നൽകുന്നത് എളുപ്പമാക്കുന്നു കൂടുതൽ ഘടനാപരമായ പ്രതിബദ്ധതയുള്ള ചരിത്രം. ## FAQ (പതിവുചോദ്യങ്ങൾ) ### പ്രാരംഭ വികസന ഘട്ടത്തിൽ കമ്മിറ്റ് സന്ദേശങ്ങൾ ഞാൻ എങ്ങനെ കൈകാര്യം ചെയ്യണം? നിങ്ങൾ ഇതിനകം ഉൽപ്പന്നം പുറത്തിറക്കിയതുപോലെ തുടരാൻ ഞങ്ങൾ ശുപാർശ ചെയ്യുന്നു. സാധാരണ *somebody*, അത് നിങ്ങളുടെ സഹ സോഫ്റ്റ്‌വെയർ ഡെവലപ്പർമാർ ആണെങ്കിൽ പോലും, നിങ്ങളുടെ സോഫ്റ്റ്‌വെയർ ഉപയോഗിക്കുന്നു. എന്താണ് ശരിയാക്കിയത്, എന്താണ് തകരുന്നത് തുടങ്ങിയവ അറിയാൻ അവർ ആഗ്രഹിക്കും. ### കമ്മിറ്റ് തലക്കെട്ടിലെ തരങ്ങൾ വലിയക്ഷരമാണോ ചെറിയക്ഷരമാണോ? ഏത് കേസിംഗും ഉപയോഗിക്കാം, പക്ഷേ സ്ഥിരത പുലർത്തുന്നതാണ് നല്ലത്. ### പ്രതിബദ്ധത ഒന്നിലധികം കമ്മിറ്റ് തരങ്ങളുമായി പൊരുത്തപ്പെടുന്നെങ്കിൽ ഞാൻ എന്തുചെയ്യും? തിരികെ പോയി സാധ്യമാകുമ്പോഴെല്ലാം ഒന്നിലധികം പ്രതിബദ്ധതകൾ ഉണ്ടാക്കുക. കൂടുതൽ സംഘടിത കമ്മിറ്റുകളും PR-കളും ഉണ്ടാക്കാൻ ഞങ്ങളെ പ്രേരിപ്പിക്കാനുള്ള കഴിവാണ് പരമ്പരാഗത കമ്മിറ്റുകളുടെ പ്രയോജനത്തിന്റെ ഭാഗം. ### ഇത് ദ്രുതഗതിയിലുള്ള വികസനത്തെയും വേഗത്തിലുള്ള ആവർത്തനത്തെയും നിരുത്സാഹപ്പെടുത്തുന്നില്ലേ? ഇത് ക്രമരഹിതമായ രീതിയിൽ വേഗത്തിൽ നീങ്ങുന്നത് നിരുത്സാഹപ്പെടുത്തുന്നു. വ്യത്യസ്‌ത സംഭാവകർക്കൊപ്പം ഒന്നിലധികം പ്രോജക്‌റ്റുകളിലുടനീളം വേഗത്തിൽ ദീർഘകാലത്തേക്ക് നീങ്ങാൻ ഇത് നിങ്ങളെ സഹായിക്കുന്നു. ### കൺവെൻഷണൽ കമ്മിറ്റുകൾ ഡെവലപ്പർമാരെ അവർ ചെയ്യുന്ന തരത്തിലുള്ള പ്രതിബദ്ധതകൾ പരിമിതപ്പെടുത്താൻ ഇടയാക്കുമോ, കാരണം അവർ നൽകിയിരിക്കുന്ന തരത്തിൽ ചിന്തിക്കും? പരിഹാരങ്ങൾ പോലുള്ള ചില പ്രത്യേക കമ്മിറ്റുകൾ കൂടുതൽ ചെയ്യാൻ പരമ്പരാഗത കമ്മിറ്റുകൾ ഞങ്ങളെ പ്രോത്സാഹിപ്പിക്കുന്നു. അതുകൂടാതെ, പരമ്പരാഗത കമ്മിറ്റുകളുടെ വഴക്കം നിങ്ങളുടെ ടീമിനെ അവരുടേതായ തരങ്ങളുമായി വരാനും കാലക്രമേണ ആ തരങ്ങൾ മാറ്റാനും അനുവദിക്കുന്നു. ### ഇത് SemVer-മായി എങ്ങനെ ബന്ധപ്പെട്ടിരിക്കുന്നു? പ്രതിബദ്ധത തരം `fix` എന്നത് ഒരു`PATCH` പതിപ്പ് മാറ്റത്തിലേക്ക് വിവർത്തനം ചെയ്യുന്നു. പ്രതിബദ്ധത തരം `feat` എന്നത് ഒരു`MINOR` പതിപ്പ് മാറ്റത്തിലേക്ക് വിവർത്തനം ചെയ്യുന്നു. `BREAKING CHANGE` എന്ന ടെക്‌സ്‌റ്റുള്ള പ്രതിബദ്ധതകൾ, അവയുടെ തരം പരിഗണിക്കാതെ തന്നെ, ഒരു `MAJOR` പതിപ്പ് മാറ്റത്തിലേക്ക് വിവർത്തനം ചെയ്യപ്പെടും. ### എന്റെ വിപുലീകരണങ്ങൾ പരമ്പരാഗത കമ്മിറ്റ് സ്പെസിഫിക്കേഷനിലേക്ക് എങ്ങനെ പതിപ്പിക്കണം, ഉദാ. `@ jameswomack / conventional-commit-spec`? ഈ സ്‌പെക്കിലേക്ക് നിങ്ങളുടെ സ്വന്തം വിപുലീകരണം റിലീസ് ചെയ്യാൻ SemVer ഉപയോഗിക്കാൻ ഞങ്ങൾ ശുപാർശ ചെയ്യുന്നു (കൂടാതെ ഈ വിപുലീകരണം നടത്താൻ ഞങ്ങൾ നിങ്ങളെ പ്രോത്സാഹിപ്പിക്കുന്നു!) ### ഞാൻ അബദ്ധവശാൽ തെറ്റായ കമ്മിറ്റ് തരം ഉപയോഗിച്ചാൽ ഞാൻ എന്തുചെയ്യും? #### നിങ്ങൾ സ്പെസിഫിക്കേഷനുള്ളതും എന്നാൽ ശരിയായ തരമല്ലാത്തതുമായ ഒരു തരം ഉപയോഗിക്കുമ്പോൾ, ഉദാ. `feat` എന്നതിന് പകരം `fix` തെറ്റ് ലയിപ്പിക്കുന്നതിനോ പുറത്തുവിടുന്നതിനോ മുമ്പ്, കമ്മിറ്റ് ഹിസ്റ്ററി എഡിറ്റ് ചെയ്യാൻ `git rebase -i` ഉപയോഗിക്കാൻ ഞങ്ങൾ ശുപാർശ ചെയ്യുന്നു. റിലീസിന് ശേഷം, നിങ്ങൾ ഉപയോഗിക്കുന്ന ഉപകരണങ്ങളും പ്രക്രിയകളും അനുസരിച്ച് വൃത്തിയാക്കൽ വ്യത്യസ്തമായിരിക്കും. #### നിങ്ങൾ സ്‌പെക്കിന്റെ *not* എന്ന തരം ഉപയോഗിക്കുമ്പോൾ, ഉദാ. `feat` എന്നതിന് പകരം `feet` ഏറ്റവും മോശം സാഹചര്യത്തിൽ, ഒരു കമ്മിറ്റ് കൺവെൻഷണൽ കമ്മിറ്റ് സ്പെസിഫിക്കേഷൻ പാലിക്കുന്നില്ലെങ്കിൽ അത് ലോകാവസാനമല്ല. സ്‌പെക്കിനെ അടിസ്ഥാനമാക്കിയുള്ള ടൂളുകളാൽ പ്രതിബദ്ധത നഷ്‌ടമാകുമെന്നാണ് ഇതിനർത്ഥം. ### എന്റെ എല്ലാ സംഭാവകരും പരമ്പരാഗത കമ്മിറ്റ് സ്പെസിഫിക്കേഷൻ ഉപയോഗിക്കേണ്ടതുണ്ടോ? ഇല്ല! നിങ്ങൾ Git-ൽ സ്ക്വാഷ് അധിഷ്‌ഠിത വർക്ക്‌ഫ്ലോ ഉപയോഗിക്കുകയാണെങ്കിൽ ലീഡ് മെയിന്റനർമാർക്ക് കമ്മിറ്റ് മെസേജുകൾ ലയിപ്പിക്കുമ്പോൾ അവ വൃത്തിയാക്കാൻ കഴിയും-കാഷ്വൽ കമ്മിറ്ററുകളിൽ ജോലിഭാരം ചേർക്കുന്നില്ല. ഒരു പുൾ അഭ്യർത്ഥനയിൽ നിന്ന് നിങ്ങളുടെ ജിറ്റ് സിസ്റ്റം സ്വയമേവ സ്ക്വാഷ് ചെയ്യപ്പെടുകയും ലയനത്തിനായി ശരിയായ ജിറ്റ് കമ്മിറ്റ് സന്ദേശം നൽകുന്നതിന് ലീഡ് മെയിന്റനർക്കായി ഒരു ഫോം അവതരിപ്പിക്കുകയും ചെയ്യുക എന്നതാണ് ഇതിനുള്ള ഒരു പൊതു വർക്ക്ഫ്ലോ. ### കൺവെൻഷണൽ കമ്മിറ്റുകൾ എങ്ങനെയാണ് റിവർട്ട് കമ്മിറ്റുകൾ കൈകാര്യം ചെയ്യുന്നത്? കോഡ് പഴയപടിയാക്കുന്നത് സങ്കീർണ്ണമായേക്കാം: നിങ്ങൾ ഒന്നിലധികം കമ്മിറ്റുകൾ പഴയപടിയാക്കുകയാണോ? നിങ്ങൾ ഒരു ഫീച്ചർ പഴയപടിയാക്കുകയാണെങ്കിൽ, അടുത്ത റിലീസ് ഒരു പാച്ച് ആയിരിക്കണമോ? പരമ്പരാഗത കമ്മീഷനുകൾ വിപരീത സ്വഭാവം നിർവചിക്കുന്നതിന് വ്യക്തമായ ശ്രമം നടത്തുന്നില്ല. പകരം, ഞങ്ങൾ അത് ടൂളിങ്ങിന് വിടുന്നു റിവേർട്ടുകൾ കൈകാര്യം ചെയ്യുന്നതിനുള്ള യുക്തി വികസിപ്പിക്കുന്നതിന് രചയിതാക്കൾ _types_, _footers_ എന്നിവയുടെ വഴക്കം ഉപയോഗിക്കുന്നു. ഒരു ശുപാർശ, `റീവർട്ട്` തരവും പഴയപടിയാക്കപ്പെടുന്ന പ്രതിബദ്ധതയുള്ള SHA-കളെ പരാമർശിക്കുന്ന ഒരു അടിക്കുറിപ്പും ഉപയോഗിക്കുക എന്നതാണ്: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.nl.md ================================================ --- draft: false aliases: ["/nl/"] --- # Conventionele Commits 1.0.0 ## Samenvatting De Conventionele Commits-specificatie is een eenvoudige conventie gebaseerd op commit-berichten. Het biedt een eenvoudige set regels voor het maken van een gestructureerde commit-geschiedenis; waardoor het gemakkelijker wordt om er geautomatiseerde tools op te baseren. Deze conventie sluit naadloos aan bij [SemVer](http://semver.org) door nieuwe functies, correcties en wijzigingen in commit-berichten te beschrijven. Het commit-bericht moet als volgt zijn gestructureerd: --- ``` [optioneel domein]: [optioneel uitgebreide omschrijving] [optioneel voettekst(en)] ``` ---
Het commit-bericht bevat de volgende structurele elementen om de uitwerking te communiceren met de gebruikers van de applicatie/bibliotheek: 1. **fix:** een commit met _type_ `fix` patcht een bug in de codebase (dit correleert met [`PATCH`](http://semver.org/#summary) in Semantic Versioning). 2. **feat:** een commit met _type_ `feat` introduceert een nieuwe functie in de codebase (dit correleert met [`MINOR`](http://semver.org/#summary) in Semantic Versioning). 3. **BREAKING CHANGE:** een commit met de voettekst `BREAKING CHANGE:`, of met een `!` direct na type/domein, introduceert een brekende API-wijziging (correlerend met [`MAJOR`](http://semver.org/#summary) in Semantic Versioning). Een BREAKING CHANGE kan altijd onderdeel van een commit-bericht, ongeacht het _type_. 4. _typen_ anders dan `fix:` en `feat:` zijn toegestaan. Zo adviseert [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (gebaseerd op de [de Angular-conventie](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) het gebruik van `build:`, `chore: `, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` en meer. 5. _voettekst(en)_ anders dan `BREAKING CHANGE: ` kunnen worden toegepast volgens een conventie vergelijkbaar met die van [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Additionele typen zijn niet verplicht volgens de Conventionele Commits-specificatie en hebben geen direct effect in Semantic Versioning (tenzij ze een BREAKING CHANGE bevatten).

Een domein kan worden meegegeven aan het _type_ van een commit om aanvullende contextuele informatie te verschaffen en dient, direct achter het _type_ en tussen haakjes, geplaatst te worden, bijv. `feat(parser): add ability to parse arrays`. ## Voorbeelden ### Commit-bericht met omschrijving en BREAKING CHANGE als voettekst ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit-bericht met `!` om een breaking change uit te lichten ``` feat!: send an email to the customer when a product is shipped ``` ### Commit-bericht inclusief domein en een `!` om een breaking change uit te lichten ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit-bericht met zowel een `!` als BREAKING CHANGE in de voettekst ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit-bericht zonder uitgebreide omschrijving ``` docs: correct spelling of CHANGELOG ``` ### Commit-bericht inclusief domein ``` feat(lang): add Polish language ``` ### Commit-bericht met meerdere paragrafen in de uitgebreide omschrijving en meerdere voetteksten ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specificatie De woorden "MOET", "MOGEN NIET", "VEREIST", "ZAL", "ZAL NIET", "ZOU", "ZOU NIET", "AANBEVOLEN", "MAG" en "OPTIONEEL" in dit document zijn te interpreteren zoals beschreven in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Een commit-bericht MOET starten met het type, dat bestaat uit een zelfstandig naamwoord, `feat`, `fix`, enz., gevolgd door een OPTIONEEL domein, OPTIONEEL `!` en VEREIST een dubbele punt en spatie. 2. Het type `feat` MOET gebruikt worden wanneer een commit een nieuwe functie toevoegt aan de applicatie/bibliotheek. 3. Het type `fix` MOET worden gebruikt wanneer een commit een bugfix in de codebase vertegenwoordigt. 4. Een domein MAG na een type worden opgegeven. Een domein MOET bestaan uit een zelfstandig naamwoord dat een gedeelte van de codebase, omgeven door haakjes, bijv. `fix(parser):` omvat. 5. Een omschrijving MOET opgegeven worden direct na de dubbele punt + spatie na het type/domein. De omschrijving is een korte samenvatting van de wijzigingen, bijv. _fix: array parsing issue when multiple spaces were contained in string_. 6. Een uitgebreide omschrijving MAG worden opgegeven voor aanvullende contextuele informatie over de wijzigingen. De uitgebreide omschrijving MOET één lege regel laten tussen de regel met het type/domein en de (korte) omschrijving. 7. De uitgbreide omschrijving is een veld dat MAG bestaan uit een willekeurig aantal, door lege regels gescheiden, alinea's. 8. Een voettekst (meedere toegestaan) MAG, na één lege regel achter de uitgebreide omschrijving, worden opgegeven. Elke voettekst MOET bestaan uit een kenmerk, gevolgd door `:` of `#`, gevolgd door een tekenreeks (dit is geïnspireerd op de [git trailer-convention](https://git-scm.com/docs/git-interpret-trailers)). 9. Een kenmerk van een voettekst MOET `-` gebruiken in plaats van spatie, bijv. `Acked-by` (dit helpt bij het onderscheiden het voettekstgedeelte en een uitgebreide omschrijving met meerdere alinea's). Een uitzondering wordt gemaakt voor `BREAKING CHANGE`, dat ook als kenmerk MAG worden gebruikt. 10. De tekenreeks van een voettekst MAG spaties en nieuwe regels bevatten en d.m.v. parsing MOET de volgende geldige voettekst (kenmerk/tekenrekens combinatie) worden waargenomen. 11. Brekende wijzigingen MOETEN worden opgegeven in het type/domein-voorvoegsel van een commit-bericht of als een geldige regel in de voettekst. 12. Indien opgegeven in de voettekst, MOET een brekende wijziging bestaan uit de tekst BREAKING CHANGE in hoofdletters, gevolgd door een dubbele punt, spatie en een omschrijving, bijv. _BREAKING CHANGE: environment variables now take precedence over config files_. 13. Indien opgegeven in het type/domein-voorvoegsel, MOET een brekende wijziging worden aangegeven met een `!` direct voor de `:`. Als `!` wordt gebruikt, MAG `BREAKING CHANGE:` worden weggelaten uit het voettekstgedeelte en de uigebreide omschrijving MOET worden gebruikt om de brekende wijziging te beschrijven. 14. Een ander type dan `feat` of `fix` MAG worden gebruikt in het commit-bericht, bijv. _docs: updated ref docs._ 15. De elementen waaruit Conventionele Commits is opgebouwd, MOGEN NIET worden beschouwd als hoofdlettergevoelig, met uitzondering van BREAKING CHANGE, dat in hoofdletters geschreven MOET worden. 16. BREAKING-CHANGE MOET een synoniem zijn voor BREAKING CHANGE wanneer gebruikt als een kenmerk in een voettekst. ## Waarom Conventionele Commits gebruiken * Automatisch CHANGELOG's genereren. * Automatisch bepalen van een semantic version bump (gebaseerd op typen van commits). * Communiceren van veranderingen aan collega's, het publiek en andere belanghebbenden. * Activeren van build- en publish-processen. * Het voor andere mensen gemakkelijker maken om bij te dragen aan projecten d.m.v. inzage in een gestructureerdere commit-geschiedenis. ## Veel gestelde vragen ### Hoe moet ik omgaan met commit-berichten in de initiële ontwikkelingsfase? We raden aan te werk te gaan alsof het product al is uitgebracht. Doorgaans gebruikt *iemand*, al zijn het slechts collega's, de software al. Zij willen weten wat er is aangepast, wat (nog) niet werkt, enz. ### Zijn de typen in de titel van een commit-bericht hoofdletters of kleine letters? Elke vorm kan worden gebruikt, al het is verstandig om hier consistent in te zijn. ### Wat moet ik doen als een commit valt onder meer dan een van de commit-typen? Ga terug en maak waar mogelijk meerdere commits. Het voordeel van het gebruik van Conventionele Commits is het vermogen om ons ertoe aan te zetten meer georganiseerde commits en PR's te maken. ### Ontmoedigt dit snelle ontwikkeling en snelle iteratie niet? Het ontmoedigt snel te ontwikkelen op een ongeorganiseerde manier. Het helpt juist om op lange termijn snel over meerdere projecten, met verschillende bijdragers, te ontwikkelen. ### Kunnen Conventionele Commits ertoe kunnen leiden dat ontwikkelaars beperkte type commits maken omdat ze zullen denken in de beschikbare typen? Conventionele Commits moedigt aan om meer van bepaalde typen commits te maken, zoals fixes. Afgezien daarvan stelt de flexibiliteit van Conventionele Commits een team in staat om eigen typen te bedenken en deze in de loop van de tijd te veranderen. ### Hoe verhoudt dit zich tot SemVer? Commits van het type `fix` moeten worden vertaald naar `PATCH`-releases. Commits van het type `feat` moeten worden vertaald naar releases van het type `MINOR`. Commits met `BREAKING CHANGE` in het commit-bericht, ongeacht het type, moeten worden vertaald naar `MAJOR`-releases. ### Hoe moet ik mijn extensies aanpassen aan de Conventionele Commits-specificatie, bijv. `@jameswomack/conventional-commit-spec`? We raden aan om SemVer te gebruiken om eigen extensies voor deze specificatie uit te brengen (en moedigen je aan om deze extensies te maken!) ### Wat moet ik doen als ik per ongeluk het verkeerde type commit gebruik? #### Als je een type hebt gebruikt dat voldoet aan de specificaties, maar niet het juiste type, bijv. `fix` in plaats van `feat` Voor het mergen of openbaar maken van deze foutieve commit, raden we aan om `git rebase -i` te gebruiken om de commit-geschiedenis te bewerken. #### Wanneer je een type gebruikt hebt dat *niet* tot de specificatie behoort, bijv. `feet` in plaats van `feat` Het is niet het einde van de wereld als een commit niet volledig voldoet aan de Conventionele Commit-specificatie. Dit kan echter wel betekenen dat commits worden gemist door (automatische) tools die zijn gebaseerd op de specificatie. ### Moeten al mijn bijdragers de Conventionele Commit-specificatie gebruiken? Nee! Als je een op squash gebaseerde workflow van git gebruikt, kunnen maintainers de commit-berichten opschonen wanneer ze deze mergen. Dit vereist geen aanpassing en/of extra werk van bijdragers. Een veelgebruikte workflow hiervoor is om het git-systeem automatisch commits te laten squashen bij een pull request en de maintainers een formulier te bieden om het gewenste commit-bericht op te geven om zo de merge te beschrijven. ### Hoe gaat de Conventionele Commits-specificatie om met teruggedraaide commits? Het terugdraaien van code kan ingewikkeld zijn: draai je meerdere commits terug? Als je een feature terugdraait, moet de volgende release dan een patch zijn? De Conventionele Commits-specificatie heeft geen vaste regels m.b.t. het terugdaaien van commits. In plaats daarvan laten we tooling auteurs vrij om de flexibiliteit van _typen_ en _voettekst(en)_ te gebruiken om eigen regels te ontwikkelen m.b.t. het terugdraaien van commits. Een aanbeveling is om het `revert`-type te gebruiken i.c.m. een voettekst die verwijst naar de commit SHA's die worden teruggedraaid: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.pl.md ================================================ --- draft: false aliases: ["/pl/"] --- # Conventional Commits 1.0.0 ## Podsumowanie Specyfikacja Conventional Commits to lekka konwencja dotycząca wiadomości commitów. Zapewnia prosty zestaw reguł do tworzenia przejrzystej historii commitów; co ułatwia budowanie narzędzi automatyzujących na jej podstawie. Ta konwencja współgra z [SemVer](http://semver.org), opisując funkcje, poprawki i breaking changes w wiadomościach commitów. Wiadomość commita powinna być zbudowana w następujący sposób: --- ``` [opcjonalny scope (zakres)]: [opcjonalny body (treść)] [opcjonalny footer (stopka)] ``` ---
Commit zawiera następujące elementy strukturalne, aby przekazać intencję używającym Twojej biblioteki: 1. **fix:** commit _typu_ `fix` naprawia błąd w kodzie (odpowiada [`PATCH`](http://semver.org/#summary) w Semantic Versioning). 2. **feat:** commit _typu_ `feat` wprowadza nową funkcjonalność w kodzie (odpowiada [`MINOR`](http://semver.org/#summary) w Semantic Versioning). 3. **BREAKING CHANGE:** commit, który posiada footer (stopkę) `BREAKING CHANGE:`, lub dodaje `!` po typie/scope (zakres), wprowadza zmianę, która może zmieniać użycie API - tzw. _breaking change_ (odpowiada [`MAJOR`](http://semver.org/#summary) w Semantic Versioning). BREAKING CHANGE może być częścią commita dowolnego _typu_. 4. Dozwolone są _typy_ inne niż `fix:` i `feat:`, np. [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (bazujący na [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) zaleca `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` i inne. 5. Dozwolone są footery (stopki) inne niż `BREAKING CHANGE: `, zgodne z [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Dodatkowe typy nie są wspierane przez specyfikację Conventional Commits i nie mają wpływu na Semantic Versioning (chyba że zawierają BREAKING CHANGE).

Scope (zakres) może być dodany do typu commita, aby przekazać dodatkowy kontekst i jest umieszczany w nawiasach, np. `feat(parser): add ability to parse arrays`. ## Przykłady ### Commit message z opisem i footerm (stopką) BREAKING CHANGE ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit message z `!` zwracającym uwagę na breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### Commit message ze scope (zakresem) i `!` zwracającym uwagę na breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit message z `!` i footerm (stopką) BREAKING CHANGE ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit message bez body (treści) ``` docs: correct spelling of CHANGELOG ``` ### Commit message ze scope (zakresem) ``` feat(lang): add Polish language ``` ### Commit message z wielo-paragrafowym body (treścią) i wieloma footerami (stopkami) ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specyfikacja Słowa kluczowe „MUSI” („MUST”), „NIE MOŻE” („MUST NOT”), „WYMAGANY” („REQUIRED”), „BĘDZIE” („SHALL”), „NIE BĘDZIE” („SHALL NOT”), „POWINIEN” („SHOULD”), „NIE POWINIEN” („SHOULD NOT”), „ZALECANY” („RECOMMENDED”), „MOŻE” („MAY”) oraz „OPCJONALNY” („OPTIONAL”) w tym dokumencie należy interpretować zgodnie z [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commity MUSZĄ („MUST”) być poprzedzone typem, który składa się z rzeczownika, np. `feat`, `fix` itd., po którym może wystąpić OPCJONALNY („OPTIONAL”) scope, OPCJONALNY („OPTIONAL”) `!` oraz WYMAGANY („REQUIRED”) dwukropek i spacja. 2. Typ `feat` MUSI („MUST”) być używany, gdy commit dodaje nową funkcjonalność do aplikacji lub biblioteki. 3. Typ `fix` MUSI („MUST”) być używany, gdy commit reprezentuje poprawkę błędu w aplikacji. 4. Scope (zakres) MOŻE („MAY”) być podany po typie. Scope (zakres) MUSI („MUST”) być rzeczownikiem opisującym część bazy kodu, ujętym w nawiasy, np. `fix(parser):` 5. Opis MUSI („MUST”) natychmiast następować po dwukropku i spacji po prefiksie typu/scope (zakres). Opis to krótkie podsumowanie zmian w kodzie, np. _fix: array parsing issue when multiple spaces were contained in string_. 6. Dłuższy body (treść) commita MOŻE („MAY”) być podany po krótkim opisie, dostarczając dodatkowych informacji o zmianach. Body (treść) MUSI („MUST”) zaczynać się jedną pustą linią po opisie. 7. Body (treść) commita jest dowolne i MOŻE („MAY”) składać się z dowolnej liczby akapitów oddzielonych nową linią. 8. Jeden lub więcej footerów (stopek) MOŻE („MAY”) być podanych jedną pustą linią po body (treści). Każdy footer (stopka) MUSI („MUST”) składać się z tokena słownego, po którym następuje separator `:` lub `#`, a następnie wartość tekstowa (inspirowane [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 9. Token footera (stopki) MUSI („MUST”) używać `-` zamiast spacji, np. `Acked-by` (to pomaga odróżnić sekcję footerów (stopek) od wielo-paragrafowego body (treści)). Wyjątkiem jest `BREAKING CHANGE`, który MOŻE („MAY”) być również użyty jako token. 10. Wartość footera (stopki) MOŻE („MAY”) zawierać spacje i nowe linie, a parsowanie MUSI („MUST”) zakończyć się, gdy napotkany zostanie kolejny poprawny token/separator footera (stopki). 11. Breaking changes MUSZĄ („MUST”) być wskazane w prefiksie typu/scope commita lub jako wpis w footerze. 12. Jeśli breaking change jest podany jako footer, MUSI („MUST”) składać się z wielkich liter BREAKING CHANGE, po których następuje dwukropek, spacja i opis, np. _BREAKING CHANGE: environment variables now take precedence over config files_. 13. Jeśli breaking change jest podany w prefiksie typu/scope, MUSI („MUST”) być oznaczony przez `!` bezpośrednio przed `:`. Jeśli użyto `!`, `BREAKING CHANGE:` MOŻE („MAY”) być pominięty w sekcji footer, a opis commita POWINIEN („SHOULD”) opisywać breaking change. 14. Typy inne niż `feat` i `fix` MOGĄ („MAY”) być używane w wiadomościach commitów, np. _docs: update ref docs._ 15. Jednostki informacji składające się na Conventional Commits NIE POWINNY („SHOULD NOT”) być traktowane jako rozróżniające wielkość liter przez implementatorów, z wyjątkiem BREAKING CHANGE, który MUSI („MUST”) być wielkimi literami. 16. BREAKING-CHANGE MUSI („MUST”) być synonimem BREAKING CHANGE, gdy jest używany jako token w footerze. ## Dlaczego warto używać Conventional Commits * Automatyczne generowanie listy zmian (CHANGELOG). * Automatyczne podbicia wersji semantycznej (na podstawie typów commitów). * Komunikowanie charakteru zmian współpracownikom, społeczności i innym zainteresowanym. * Wyzwalanie procesów budowania i publikacji. * Ułatwienie osobom z zewnątrz kontrybuowania do projektu poprzez bardziej uporządkowaną historię commitów. ## FAQ ### Jak postępować z wiadomościami commitów w fazie początkowego rozwoju? Zalecamy traktować projekt tak, jakby był już publicznie wydany. Zazwyczaj _ktoś_ (nawet jeśli to tylko inni programiści) korzysta z Twojego oprogramowania i chce wiedzieć, co zostało naprawione, co się zmieniło, a co może nie działać. ### Czy typy w tytule commita powinny być pisane wielkimi czy małymi literami? Możesz używać zarówno wielkich, jak i małych liter, ale najważniejsza jest konsekwencja. ### Co zrobić, jeśli commit pasuje do więcej niż jednego typu? Jeśli to możliwe, rozdziel zmiany na osobne commity. Jedną z zalet Conventional Commits jest zachęcanie do bardziej uporządkowanej historii commitów i pull requestów. ### Czy to nie zniechęca do szybkiego rozwoju i iteracji? To nie zniechęca do szybkiego rozwoju, ale do nieuporządkowanego działania. W dłuższej perspektywie ułatwia szybki rozwój projektów z wieloma współautorami. ### Czy Conventional Commits mogą ograniczać typy commitów, bo programiści będą myśleć tylko o podanych typach? Conventional Commits zachęca do częstszego używania niektórych typów commitów, np. `fix`. Poza tym konwencja jest elastyczna – zespół może definiować własne typy commitów i zmieniać je w miarę potrzeb. ### Jaki to ma związek z SemVer? Commity typu `fix` powinny skutkować wydaniem wersji `PATCH`, typu `feat` – wersji `MINOR`, a commity z `BREAKING CHANGE` (niezależnie od typu) – wersji `MAJOR`. ### Jak wersjonować własne rozszerzenia specyfikacji Conventional Commits? Zalecamy używanie SemVer do wersjonowania własnych rozszerzeń tej specyfikacji (i zachęcamy do ich tworzenia!). ### Co zrobić, jeśli przez pomyłkę użyję złego typu commita? * Jeśli użyłeś typu zgodnego ze specyfikacją, ale nieodpowiedniego (np. `fix` zamiast `feat`): Przed mergem lub wydaniem zalecamy użycie `git rebase -i` do edycji historii commitów. Po wydaniu sposób poprawy zależy od używanych narzędzi i procesów. * Jeśli użyłeś typu *nie*zgodnego ze specyfikacją (np. `feet` zamiast `feat`): W najgorszym przypadku taki commit po prostu nie zostanie uwzględniony przez narzędzia korzystające ze specyfikacji Conventional Commits. ### Czy wszyscy kontrybutorzy muszą stosować Conventional Commits? Nie! Jeśli korzystasz z workflow opartego na squashowaniu commitów, główni maintainerzy mogą poprawiać wiadomości commitów podczas mergowania – bez dodatkowego obciążenia dla okazjonalnych kontrybutorów. Często system git automatycznie squashuje commity z pull requesta i pozwala maintainerowi wpisać właściwą wiadomość commita podczas scalania. ### Jak Conventional Commits obsługuje commity typu revert? Revertowanie kodu może być złożone: czy cofamy wiele commitów? Jeśli cofamy funkcję, czy następne wydanie powinno być patch? Conventional Commits nie określa szczegółowo, jak obsługiwać commity typu revert – pozostawia to narzędziom i autorom logiki. Zalecamy użycie typu `revert` oraz stopki z referencją do SHA commitów, które są cofane: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ## Podsumowanie Specyfikacja Conventional Commits to lekka konwencja dotycząca wiadomości commitów, która zapewnia prosty zestaw reguł do tworzenia przejrzystej historii commitów i ułatwia budowanie narzędzi automatyzujących. Jest zgodna z SemVer, opisując funkcje, poprawki i breaking changes w commitach. ================================================ FILE: content/v1.0.0/index.pr.md ================================================ --- draft: false aliases: ["/pr/"] --- # Conventional Commits 1.0.0 ## خلاصه مشخصات Commits Conventional یک قرارداد سبک وزن در بالای پیام های commit است. این مجموعه قوانین آسانی را برای ایجاد یک تاریخچه ارتکاب صریح فراهم می کند. که نوشتن ابزارهای خودکار در بالای آن را آسان تر می کند. این کنوانسیون با [SemVer] (http://semver.org) مطابقت دارد، با تشریح ویژگی‌ها، اصلاحات، و شکستن تغییرات ایجاد شده در پیام‌های commit. ساختار پیام commit باید به صورت زیر باشد: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
کامیت استاندارد شامل المان های ساختاری زیر است تا کاربرات ارتباط بهتری با کتابخانه شما برقرار کنند: 1. **fix:** کامیت نوع `fix` نشانگر اصلاح یک باگ در کد شماست(مصداق [`PATCH`](http://semver.org/#summary) در ورژن‌بندی سمانتیک) 2. **feat:** کامیت نوع `feat` ایجاد یک ویژگی جدید را در کد معرفی میکند(مصداق [`MINOR`](http://semver.org/#summary) در ورژن‌بندی سمانتیک) 3. **BREAKING CHANGE:** یک کامیت که شامل فوتر با عنوان `BREAKING CHANGE:` باشد یا `!` در کنار نوع/اسکوپ آن آمده باشد معرف یک تغییر ناسازگار (Breaking Change) در API است. (مصداق [`MAJOR`](http://semver.org/#summary) در ورژن‌بندی سمانتیک) BREAKING CHANGE می‌تواند بخشی از هر نوع کامیت باشد. 4. انواع دیگری بغیر از `fix:` و `feat` نیز مجاز هستند. بعنوان مثال [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (بر پایه [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, و غیره را پیشنهاد می‌دهد. 5. فوتر های دیگری نیز بجز `BREAKING CHANGE: ` ممکن است اراوه شوند و از قاعده [git trailer format](https://git-scm.com/docs/git-interpret-trailers) پیروی کنند. نواع (Types) اضافی دیگر در مشخصات Conventional Commits اجباری نیستند و به‌طور پیش‌فرض تأثیری در نسخه‌بندی معنایی (Semantic Versioning) ندارند (مگر اینکه شامل یک BREAKING CHANGE باشند).

همچنین می‌توان برای نوع (Type) یک کامیت، یک اسکوپ (Scope) تعریف کرد تا اطلاعات بیشتری در مورد زمینه تغییرات ارائه دهد. اسکوپ داخل پرانتز قرار می‌گیرد؛ به‌عنوان مثال: `feat(parser): add ability to parse arrays` ## مثال ### کامیت همراه با توضیح و فوتر Breaking Change ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### کامیت همراه `!` بمنظور جلب توجه برای BREAKING CHANGE ``` feat!: send an email to the customer when a product is shipped ``` ### کامیت همراه اسکوپ و `!` بمنظور جلب توجه برای BREAKING CHANGE ``` feat(api)!: send an email to the customer when a product is shipped ``` ### کامیت همراه `!` و فوتر BREAKING CHANGE بطور همزمان ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### کامیت بدون توضیح ``` docs: correct spelling of CHANGELOG ``` ### کامیت همراه اسکوپ ``` feat(lang): add Polish language ``` ### کامیت همراه چندین خط توضیح و چندین خط فوتر ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## مشحصات کلمات کلیدی “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” باید طبق [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) تفسیر شوند. 1. کامیت‌ها باید(MUST) با یک نوع مانند `feat`, `fix` و غیره شروع شوند و اسکوپ و `!` بصورت اختیاری(OPTIONAL) در ادامه آورده شود که دونقطه و فاصله ضروری(REQUIRED) است. 2. نوع `feat` باید(MUST) وقتی استفاده شود که کامیت یک ویژگی جدید به برنامه یا کتابخانه شما اضافه کند. 3. نوع `fix` باید(MUST) وقتی استفاده شود که کامیت یک باگ از برنامه یا کتابخانه شما برطرف کند. 4. ممکن(MAY) است بعد از نوع اسکوپ بیان شود. یک اسکوب باید(MUST) یک اسم داخل پرانتز باشد که اسکوپ کامیت را توضیح دهد، بعنوان مثال `fix(parser):` 5. توضیح باید(MUST) بلافاصله بعد از دونقطه و فاصله پس از نوع/اسک.پ آورده شود. این توضیح شامل یک متن کوتاه درباره تغییر درحال کامیت است، مثلا _fix: array parsing issue when multiple spaces were contained in string_. 6. ممکن(MAY) است پس از توضیحات کوتاه، توضیح طولانی‌تری ارائه شود که اطلاعات متنی بیشتری در مورد تغییرات کد ارائه می‌کند. متن باید یک خط خالی بعد از توضیحات اول شروع شود. 7. بصورت آزاد است و ممکن(MAY) است از هر تعداد پاراگراف جدا شده از خط جدید تشکیل شده باشد. 8. ممکن(MAY) است یک یا چند فوتر بعد از یک خط خالی بعد از بدنه توضیحات ارائه شود. هر فوتر باید(MUST) شامل یک توکن (کلمه کلیدی) باشد که به دنبال آن یک جداکننده : (دو نقطه و یک فاصله) یا # (یک فاصله و علامت #) قرار می‌گیرد و سپس یک مقدار متنی (String Value) (این قالب‌بندی از کنوانسیون تریلرهای گیت [git trailer convention](https://git-scm.com/docs/git-interpret-trailers) الهام گرفته شده است). 9. نشانه فوتر باید(MUST) از «-» به جای کاراکترهای فضای خالی استفاده کند، به عنوان مثال، «Acked-by» (این به تمایز بخش t,jv از بدنه کمک می کند). یک استثنا برای `BREAKING CHANGE` ایجاد شده است که ممکن است به عنوان نشانه نیز استفاده شود. 10. مقدار فوتر ممکن(MAY) است حاوی فاصله و خطوط جدید باشد و پارسر باید(MUST) با مشاهده جفت نشانه/جداکننده فوتر معتبر بعدی خاتمه یابد. 11. BREAKING CHANGE باید(MUST) در پیشوند نوع/حوزه یک کامیت یا به عنوان ابتدای فوتر حضور داشته باشد. 12. اگر BREAKING CHANGE در فوتر گنجانده شود، آن(MUST) حروف بزرگ BREAKING CHANGE، به دنبال آن دو نقطه، فاصله و توضیحات باشد، به عنوان مثال، مثلا _BREAKING CHANGE: environment variables now take precedence over config files_. 13. اگر BREAKING CHANGE در ابتدای کامیت گنجانده شود، باید(MUST) با یک `!` بلافاصله قبل از `:` نشان داده شود. اگر از `!` استفاده شود، BREAKING CHANGE ممکن(MAY) است از قسمت فوتر حذف شود، در این حال خوب است(SHALL) توضیح کامیت باید برای توصیف BREAKING CHANGE استفاده شود. 14. انواعی غیر از `feat` و `fix` ممکن(MAY) است در پیام‌های کامیت شما استفاده شود، به عنوان مثال _docs: update ref docs._ 15. عبارات کلیدی استاندارد کامیت نباید(MUST NOT) بعوان حساس به حروف کوچک و بزرگ شناخته شوند به استثنا BREAKING CHANGE که حروف بزرگ است. 16. BREAKING-CHANGE باید(MUST) مترادف با BREAKING CHANGE باشد، زمانی که به عنوان توکن در فوتر استفاده می شود. ## چرا از استاندارد کامیت استفاده می‌کنیم؟ * ایجاد خودکار CHANGELOG. * تعیین خودکار ورژن‌بندی سمانتیک(بر اساس نوع کامیت). * انتقال مفهوم تغییرات به هم تیمی ها، مردم و سایر ذینفعان. * راه اندازی فرآیندهای ساخت و انتشار. * ساده‌تر کردن فرآیند مشارکت بقیه افراد در پروژه با ایجاد یک تاریخچه ساختارمند از کامیت ها. ## سوالات پرتکرار ### چگونه در فاز راه‌اندازی اولیه با پیان کامیت برخورد کنم؟ توصیه می کنیم به گونه ای ادامه دهید که گویی قبلاً محصول را منتشر کرده اید. به طور معمول *کسی*، حتی اگر همکار توسعه دهندگان نرم افزار شما باشد، از نرم افزار شما استفاده می کند. آنها می خواهند بدانند چه چیزی ثابت شده است، چه چیزی خراب می شود و غیره. ### آیا نوع‌ها باید از حروف کوچک استفاده کنند یا حروف بزرگ؟ تفاوتی نم‌کند اما بهتر است یکدست باشد. ### اگر گامیت با بیش از یک نوع از انواع استاندارد مطابقت داشت، چه کاری باید بکنم؟ ترجیحا به عقب برگردید و کامیت های بیشتری تولید کنید. بخشی از مزایای قاعده استاندارد توانایی آن در سوق دادن ما به انجام تعهدات و روابط عمومی بیشتر است. ### آیا این موضوع باعث کاهش سرعت توسعه نمی‌شود؟ این روش، حرکت سریع اما بی‌نظم را محدود می‌کند. در عوض، به شما کمک می‌کند تا در بلندمدت و در پروژه‌های مختلف با مشارکت‌کنندگان متنوع، به‌صورت کارآمد و سازمان‌یافته پیش بروید. ### آیا قاعده استاندارد کامیت ممکن است باعث شود توسعه‌دهندگان نوع کامیت‌های خود را محدود کنند، زیرا آن‌ها به انواع تعیین‌شده فکر می‌کنند؟ قاعده استاندارد کامیت توسعه‌دهندگان را تشویق می‌کند تا تعداد بیشتری از کامیت‌های خاص مانند کامیت‌های اصلاحی ایجاد کنند. علاوه بر این، انعطاف‌پذیری قاعده استاندارد کامیت به تیم شما این امکان را می‌دهد که انواع خود را تعریف کرده و آن‌ها را در طول زمان تغییر دهند. ### این موضوع چگونه به SemVer مرتبط می‌شود؟ کامیت‌های از نوع `fix` باید به انتشارهای `PATCH` تبدیل شوند. کامیت‌های از نوع `feat` باید به انتشارهای `MINOR` تبدیل شوند. کامیت‌هایی که شامل `BREAKING CHANGE` باشند، بدون توجه به نوع آن‌ها، باید به انتشارهای `MAJOR` تبدیل شوند. ### چگونه باید نسخه‌گذاری افزونه‌های خود به مشخصات قاعده استاندارد کامیت را انجام دهم، مثلاً `@jameswomack/conventional-commit-spec`؟ ما توصیه می‌کنیم از SemVer برای انتشار افزونه‌های خود به این مشخصات استفاده کنید (و شما را تشویق می‌کنیم که این افزونه‌ها را ایجاد کنید!). ### اگر به اشتباه از نوع کامیت اشتباه استفاده کردم، چه کار باید بکنم؟ #### اگر از نوعی استفاده کرده‌اید که در مشخصات وجود دارد اما نوع صحیح نیست، مثلاً `fix` به جای `feat` قبل از ادغام یا انتشار اشتباه، توصیه می‌کنیم از `git rebase -i` برای ویرایش تاریخچه کامیت‌ها استفاده کنید. پس از انتشار، پاک‌سازی بستگی به ابزارها و فرآیندهایی دارد که استفاده می‌کنید. #### اگر از نوعی استفاده کرده‌اید که در مشخصات وجود ندارد، مثلاً `feet` به جای `feat` در بدترین حالت، اگر کامیتی که با مشخصات قاعده استاندارد کامیت مطابقت ندارد وارد شود، دنیا به پایان نمی‌رسد. این فقط به این معنی است که آن کامیت توسط ابزارهایی که بر اساس این مشخصات کار می‌کنند، نادیده گرفته خواهد شد. ### آیا همه مشارکت ککندگان پروژه من باید از مشخصات قاعده استاندارد کامیت پیروی کنند؟ نه! اگر از یک گردش کار مبتنی بر Squash در گیت استفاده کنید، نگه‌دارندگان اصلی می‌توانند پیام‌های کامیت را در حین ادغام تمیز و مرتب کنند بدون اینکه بار کاری اضافه‌ای به مشارکت‌کنندگان معمولی تحمیل شود. یک گردش کار رایج برای این مورد این است که سیستم گیت شما به‌طور خودکار کامیت‌های یک درخواست pull را Squash کند و یک فرم به نگه‌دارنده اصلی ارائه دهد تا پیام کامیت مناسب را برای ادغام وارد کند. ### قاعده استاندارد کامیت چگونه کامیت‌های بازگشتی (Revert) را مدیریت می‌کند؟ بازگرداندن کد (Revert) می‌تواند پیچیده باشد: آیا چندین کامیت را بازمی‌گردانید؟ اگر یک قابلیت را بازگردانید، آیا نسخه بعدی باید یک وصله (Patch) باشد؟ قاعده استاندارد کامیت تلاش صریحی برای تعریف رفتار بازگشتی انجام نمی‌دهد. در عوض، این امکان را به نویسندگان ابزارها می‌دهد تا از انعطاف‌پذیری انواع و فوترها استفاده کنند و منطق خود را برای مدیریت بازگردانی‌ها توسعه دهند. یک توصیه این است که از نوع revert و یک فوتر که به SHAهای کامیت‌های بازگردانی‌شده ارجاع می‌دهد، استفاده کنید: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.pt-br.md ================================================ --- draft: false aliases: ["/pt-br/"] --- # Conventional Commits 1.0.0 ## Resumo A especificação do Conventional Commits é uma convenção simples para utilizar nas mensagens de commit. Ela define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas baseadas na especificação. Esta convenção se encaixa com o [SemVer](https://semver.org/lang/pt-BR/), descrevendo os recursos, correções e modificações que quebram a compatibilidade nas mensagens de commit. A mensagem do commit deve ser estruturada da seguinte forma: --- ``` [escopo opcional]: [corpo opcional] [rodapé(s) opcional(is)] ``` ---
O commit contém os seguintes elementos estruturais, para comunicar a intenção ao utilizador da sua biblioteca: 1. **fix:** um commit do _tipo_ `fix` soluciona um problema na sua base de código (isso se correlaciona com [`PATCH`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). 1. **feat:** um commit do _tipo_ `feat` inclui um novo recurso na sua base de código (isso se correlaciona com [`MINOR`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). 1. **BREAKING CHANGE:** um commit que contém no rodapé opcional o texto `BREAKING CHANGE:`, ou contém o símbolo `!` depois do tipo/escopo, introduz uma modificação que quebra a compatibilidade da API (isso se correlaciona com [`MAJOR`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). Uma BREAKING CHANGE pode fazer parte de commits de qualquer _tipo_. 1. Outros _tipos_ adicionais são permitidos além de `fix:` e `feat:`, por exemplo [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (baseado na [Convenção do Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recomenda-se `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, entre outros. 1. Outros _rodapés_ diferentes de `BREAKING CHANGE: ` podem ser providos e seguem uma convenção similar ao [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Observe que esses tipos adicionais não são exigidos pela especificação do Conventional Commits e não têm efeito implícito no versionamento semântico (a menos que incluam uma `BREAKING CHANGE`).

Um escopo pode ser fornecido ao tipo do commit, para fornecer informações contextuais adicionais e está contido entre parênteses, por exemplo `feat(parser): adiciona capacidade de interpretar arrays`. ## Exemplos ### Mensagem de commit com descrição e modificação que quebra a compatibilidade no rodapé ``` feat: permitir que o objeto de configuração fornecido estenda outras configurações BREAKING CHANGE: a chave `extends`, no arquivo de configuração, agora é utilizada para estender outro arquivo de configuração ``` ### Mensagem de commit com `!` para chamar a atenção para quebra a compatibilidade ``` feat!: envia email para o cliente quando o produto é enviado ``` ### Mensagem de commit com escopo e `!` para chamar a atenção para quebra a compatibilidade ``` feat(api)!: envia email para o cliente quando o produto é enviado ``` ### Mensagem de commit com `!` e BREAKING CHANGE no rodapé ``` feat:! remove suporte para Node 6 BREAKING CHANGE: refatorar para usar recursos do JavaScript não disponíveis no Node 6. ``` ### Mensagem de commit sem corpo ``` docs: ortografia correta de CHANGELOG ``` ### Mensagem de commit com escopo ``` feat(lang): adiciona tradução para português brasileiro ``` ### Mensagem de commit de uma correção utilizando número de ticket (opcional) ``` fix: corrige pequenos erros de digitação no código veja o ticket para detalhes sobre os erros de digitação corrigidos Revisado por: Daniel Nass Refs #133 ``` ## Especificação As palavras-chaves “DEVE” (“MUST”), “NÃO DEVE” (“MUST NOT”), “OBRIGATÓRIO” (“REQUIRED”), “DEVERÁ” (“SHALL”), “NÃO DEVERÁ” (“SHALL NOT”), “PODEM” (“SHOULD"), “NÃO PODEM” (“SHOULD NOT”), “RECOMENDADO” (“RECOMMENDED”), “PODE” (“MAY”) e “OPCIONAL” (“OPTIONAL”), nesse documento, devem ser interpretados como descrito na [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. A mensagem de commit DEVE ser prefixado com um tipo, que consiste em um substantivo, `feat`,` fix`, etc., seguido por um escopo OPCIONAL, símbolo OPCIONAL `!`, e OBRIGATÓRIO terminar com dois-pontos e um espaço. 1. O tipo `feat` DEVE ser usado quando um commit adiciona um novo recurso ao seu aplicativo ou biblioteca. 1. O tipo `fix` DEVE ser usado quando um commit representa a correção de um problema em seu aplicativo ou biblioteca. 1. Um escopo PODE ser fornecido após um tipo. Um escopo DEVE consistir em um substantivo que descreve uma seção da base de código entre parênteses, por exemplo, `fix(parser): `. 1. Uma descrição DEVE existir depois do espaço após o prefixo tipo/escopo. A descrição é um breve resumo das alterações de código, por exemplo, _fix: problema na interpretação do array quando uma string tem vários espaços._ 1. Um corpo de mensagem de commit mais longo PODE ser fornecido após a descrição curta, fornecendo informações contextuais adicionais sobre as alterações no código. O corpo DEVE começar depois de uma linha em branco após a descrição. 1. Um corpo de mensagem de commit é livre e PODE consistir em infinitos parágrafos separados por uma nova linha. 1. PODE(M) ser fornecidos um ou mais rodapés, uma linha em branco após o corpo. Cada rodapé DEVE consistir em um token de palavra, seguido por um separador `:` ou `#`, seguido por um valor de uma string (isso é inspirado pelo [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. Um token de rodapé DEVE usar `-` no lugar de espaços em branco, por exemplo, `Acked-by` (isso ajuda a diferenciar a seção de rodapé de um corpo de vários parágrafos). Uma exceção é feita para `BREAKING CHANGE`, que PODE também ser usado como um token. 1. O valor de um rodapé PODE conter espaços e novas linhas, e a análise (parsing) DEVE terminar quando o próximo token/separador de rodapé válido for encontrado. 1. BREAKING CHANGES DEVEM ser indicadas após o tipo/escopo de uma mensagem de commit, ou como uma entrada no rodapé. 1. Se incluída como um rodapé, uma alteração de quebra DEVE consistir no texto em maiúsculas QUEBRAR ALTERAÇÃO, seguido por dois pontos, espaço e descrição, por exemplo, _BREAKING CHANGE: as variáveis de ambiente agora têm precedência sobre os arquivos de configuração_. 1. Se incluído no prefixo de tipo/escopo, as `BREAKING CHANGES` DEVEM ser indicadas por um `!` imediatamente antes de `:`. Se o símbolo `!` for usado, `BREAKING CHANGE:` PODE ser omitido da seção de rodapé, e a descrição da mensagem de commit DEVE ser usada para descrever a `BREAKING CHANGE`. 1. Tipos diferentes de `feat` e` fix` PODEM ser usados em suas mensagens de commit, por exemplo, _docs: documentos de referência atualizados_ 1. As unidades de informação que compõem o Conventional Commits NÃO DEVEM ser tratadas com distinção entre maiúsculas e minúsculas pelos implementadores, com exceção de `BREAKING CHANGE` que DEVE ser maiúscula. 1. `BREAKING-CHANGE` DEVE ser sinônimo de `BREAKING CHANGE`, quando usado como um token em um rodapé. ## Porque utilizar Conventional Commits - Criação automatizada de CHANGELOGs. - Determinar automaticamente alterações no versionamento semântico (com base nos tipos de commits). - Comunicar a natureza das mudanças para colegas de equipe, o público e outras partes interessadas. - Disparar processos de build e deploy. - Facilitar a contribuição de outras pessoas em seus projetos, permitindo que eles explorem um histórico de commits melhor estruturado. ## Perguntas Frequentes ### Como devo lidar com mensagens de commit na fase inicial de desenvolvimento? Recomendamos que você prossiga como se já tivesse lançado o produto. Normalmente _alguém_, mesmo que seja seus colegas desenvolvedores, está usando seu software. Eles vão querer saber o que foi corrigido, novas features, breaking changes etc. ### Os tipos no título das mensagens commit são maiúsculos ou minúsculos? Qualquer opção pode ser usada, mas é melhor ser consistente. ### O que eu faço se o commit estiver de acordo com mais de um dos tipos? Volte e faça vários commits sempre que possível. Parte do benefício do Conventional Commits é a capacidade de nos levar a fazer commits e PRs de forma mais organizada. ### Isso não desencoraja o desenvolvimento rápido e a iteração rápida? Desencoraja a movimentação rápida de forma desorganizada. Ele ajuda você a ser capaz de se mover rapidamente a longo prazo em vários projetos com múltiplos colaboradores. ### O Conventional Commits leva os desenvolvedores a limitar o tipo de commits que eles fazem porque estarão pensando nos tipos fornecidos? O Conventional Commits nos encorajam a fazer mais commits de tipos específicos, por exemplo correções. Além disso, a flexibilidade do Conventional Commits permite que sua equipe crie seus próprios tipos e altere ao longo do tempo. ### Qual a relação com o SemVer? Commits do tipo `fix` devem ser enviados para releases `PATCH`. Commits do tipo `feat` devem ser enviados para releases `MINOR`. Commits com `BREAKING CHANGE` nas mensagens, independentemente do tipo, devem ser enviados para releases `MAJOR`. ### Como devo versionar minhas extensões utilizando a especificação do Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? Recomendamos utilizar o [SemVer](http://semver.org) para liberar suas próprias extensões para esta especificação (e incentivamos você criar essas extensões!) ### O que eu faço se acidentalmente usar o tipo errado de commit? #### Quando você usou um tipo da especificação, mas não do tipo correto, por exemplo `fix` em vez de `feat` Antes do merge ou release com o erro, recomendamos o uso de `git rebase -i` para editar o histórico do commit. Após o release, a limpeza será diferente de acordo com as ferramentas e processos que você utiliza. #### Quando você usou um tipo que _não_ é da especificação, por exemplo `feet` em vez de `feat` Na pior das hipóteses, não é o fim do mundo se um commit não atender à especificação do Conventional Commits. Significa apenas que o commit será ignorado por ferramentas baseadas nessa especificação. ### Todos os meus colaboradores precisam usar a especificação do Conventional Commits? Não! Se você usar um workflow de git baseado em squash, os mantenedores poderão limpar as mensagens de commit à medida que forem fazendo novos merges, não adicionando carga de trabalho aos committers casuais. Um workflow comum para isso é fazer com que o git faça squash dos commits automaticamente de um pull request e apresente um formulário para o mantenedor inserir a mensagem do commit apropriada para o merge. ### Como o Conventional Commits trata os commits de reversão? Reverter código pode ser complicado: você está revertendo vários commits? se você reverter um recurso, a próxima versão deve ser um patch? O Conventional Commits não o força a definir um comportamento de reversão. Em vez disso, deixamos isso para que os autores de ferramentas usem a flexibilidade de _tipos_ e _rodapés_ para desenvolver sua própria lógica para lidar com reversões. Uma recomendação é usar o tipo `revert` e um rodapé que referencia os SHAs de commit que estão sendo revertidos: ``` revert: nunca mais falaremos do incidente do miojo Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.ro.md ================================================ --- draft: false aliases: ['/ro/'] --- # Comiteri convenționale 1.0.0 ## Rezumat Specificația Comiteri convenționale este o convenție ușoară peste mesajele de comitere. Oferă un set ușor de reguli pentru crearea unui istoric explicit de comitere; ceea ce face mai ușor să scrii instrumente automate peste. Această convenție se potrivește cu [SemVer](http://semver.org), prin descrierea caracteristicilor, remedierilor și modificărilor finale făcute în mesajele de confirmare. Mesajul de comitere ar trebui să fie structurat după cum urmează: --- ``` [domeniu de aplicare opțional]: [corp opțional] [subsol opțional] ``` ---
Mesajul de comitere conține următoarele elemente structurale, pentru a comunica intenția consumatorilor bibliotecii tale: 1. **fix:** o comitere de _tip_ `fix` corectează o eroare în codul tău de bază (aceasta se corelează cu [`PATCH`](http://semver.org/#summary) în Numerotarea Semantică). 1. **feat:** o comitere de _tip_ `feat` introduce o funcționalitate nouă în codul de bază (aceasta se corelează cu [`MINOR`](http://semver.org/#summary) în Numerotarea Semantică). 1. **BREAKING CHANGE:** o comitere care are un subsol `BREAKING CHANGE:`, sau adaugă un `!` după tip/domeniu de aplicare, introduce o modificare care afectează funcționalitatea API (se corelează cu [`MAJOR`](http://semver.org/#summary) în Numerotarea Semantică). O modificare BREAKING CHANGE poate face parte din comiteri de orice _tip_. 1. Sunt permise și alte _tipuri_ decât `fix:` și `feat:`, de exemplu [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (bazat pe [convenția Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recomandă `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, și altele. 1. Pot fi furnizate _subsoluri_, altele decât `BREAKING CHANGE: ` și urmăresc o convenție asemănătoare cu [formatul git trailer](https://git-scm.com/docs/git-interpret-trailers). Tipurile suplimentare nu sunt impuse de specificația Comiteri convenționale și nu au niciun efect implicit în Numerotarea Semantică (cu excepția cazului în care includ o modificare BREAKING CHANGE).

Un domeniu de aplicare poate fi furnizat unui tip de comitere, pentru a furniza informații contextuale suplimentare și este conținut în paranteză, de exemplu, `feat(parser): add ability to parse arrays`. ## Exemple ### Mesaj de comitere cu descriere și subsol de modificări care afectează funcționalitatea ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Mesaj de comitere cu `!` pentru pentru a atrage atenția asupra modificărilor care afectează funcționalitatea ``` feat!: send an email to the customer when a product is shipped ``` ### Mesaj de comitere cu un domeniu de aplicare și `!` pentru a atrage atenția asupra modificărilor care afectează funcționalitatea ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Mesaj de comitere și cu `!` și cu subsol de modificări care afectează funcționalitatea ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Mesaj de comitere fără corp ``` docs: correct spelling of CHANGELOG ``` ### Mesaj de comitere cu domeniu de aplicare ``` feat(lang): add Polish language ``` ### Mesaj de comitere având corp cu paragrafe și subsoluri multiple ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specificație Cuvintele cheie „TREBUIE”, „NU TREBUIE”, „NECESAR”, „AR TREBUI”, „NU AR TREBUI”, „RECOMANDAT”, „POATE”, și „OPȚIONAL” din acest document sunt să fie interpretate așa cum sunt descrise în [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Comiterile TREBUIE prefixate cu un tip, care constă dintr-un substantiv, `feat`, `fix`, etc., urmat de un domeniu de aplicare OPȚIONAL, `!` OPȚIONAL și două puncte și spațiu NECESARE. 1. Tipul `feat` TREBUIE folosit când o comitere adaugă o nouă funcționalitate aplicației sau bibliotecii tale. 1. Tipul `fix` TREBUIE folosit când o comitere reprezintă o remediere a unei erori pentru aplicația ta. 1. Un domeniu de aplicare POATE fi furnizat după un tip. Un domeniu TREBUIE să fie format dintr-un substantiv care descrie o secțiune a codului de bază înconjurată în paranteze, de exemplu, `fix(parser):` 1. O descriere TREBUIE să urmeze imediat celor două puncte și spațiului după prefixul tip/domeniu de aplicare. Descrierea este un scurt rezumat al modificărilor codului, de exemplu, _fix: array parsing issue when multiple spaces were contained in string_. 1. Un corp de comitere mai lung POATE fi furnizat după scurta descriere, oferind informații contextuale suplimentare despre modificările codului. Corpul TREBUIE să înceapă un rând liber după descriere. 1. Un corp de commitere are o formă liberă și POATE consta din orice număr de paragrafe separate de linii noi. 1. Unul sau mai multe subsoluri POT fi furnizate cu o linie goală după corp. Fiecare subsol TREBUIE să conțină un simbol de cuvânt, urmat fie de un separator `:` sau `#`, urmat de o valoare șir (aceasta este inspirată de [convenția git trailer](https://git -scm.com/docs/git-interpret-trailers)). 1. Indicatorul unui subsol TREBUIE să folosească `-` în locul caracterelor cu spații albe, de exemplu, `Acked-by` (acest lucru ajută la diferențierea secțiunilor de subsol dintr-un corp cu mai multe paragrafe). Se face o excepție pentru `BREAKING CHANGE`, care POATE fi folosit și ca simbol. 1. Valoarea unui subsol POATE conține spații și linii noi, iar interpretarea TREBUIE să se termine atunci când este observată următoarea pereche validă de simbol de subsol/separator. 1. Modificările care afectează funcționalitatea TREBUIE să fie indicate în prefixul tip/domeniu de aplicare al unuei comiteri sau ca o intrare de subsol. 1. Dacă este inclusă ca subsol, o modificare care afectează funcționalitatea TREBUIE să conțină textul cu majuscule BREAKING CHANGE, urmat de două puncte, spațiu și descriere, de exemplu, _BREAKING CHANGE: environment variables now take precedence over config files_. 1. Dacă sunt incluse în prefixul tip/domeniu de aplicare, modificările care afectează funcționalitatea TREBUIE să fie indicate prin `!` imediat înainte de `:`. Dacă se folosește `!`, `BREAKING CHANGE:` POATE fi omis din secțiunea de subsol, iar descrierea de comitere TREBUIE folosită pentru a descrie modificarea care afectează funcționalitatea. 1. Alte tipuri decât `feat` și `fix` POT fi utilizate în mesajele tale de comitere, de exemplu, _docs: update ref docs._ 1. Unitățile de informații care alcătuiesc Comiterile convenționale NU TREBUIE să fie tratate ca fiind sensibile la majuscule și minuscule de către implementatori, cu excepția BREAKING CHANGE care TREBUIE să fie majuscule. 1. BREAKING-CHANGE TREBUIE să fie sinonim cu BREAKING CHANGE, atunci când este folosit ca simbol într-un subsol. ## De ce să folosești Comiteri convenționale? - Generarea automată a jurnalelor de modificări. - Determinarea automată a unui bump semantic al versiunii (pe baza tipurilor de comiteri efectuate). - Comunicarea naturii schimbărilor colegilor de echipă, publicului și altor părți interesate. - Declanșarea proceselor de creare și publicare. - Facilitarea contribuției cu ușurință a oamenilor la proiectele tale, permițându-le să exploreze o istorie mai structurată a comiterilor. ## Întrebări și răspunsuri ### Cum ar trebui să mă ocup de mesajele de comitere în faza inițială de dezvoltare? Îți recomandăm să continui ca și cum ai fi lansat deja produsul. De obicei, _cineva_, chiar dacă este vorba de colegii tăi dezvoltatori de software, folosește software-ul tău. Vor dori să știe ce s-a reparat, ce se întrerupe etc. ### Titlurile tipurilor de comiteri sunt cu litere mari sau mici? Poți folosi orice caz, dar cel mai bine este să păstrezi consecvența. ### Ce fac dacă comiterea este conformă cu mai mult de unul dintre tipurile de comiteri? Revii și faci mai multe comiteri ori de câte ori este posibil. O parte a beneficiului Comiterilor convenționale este capacitatea lor de a ne determina să facem comiteri și PR-uri mai organizate. ### Nu descurajează acest lucru dezvoltarea și iterația rapidă? Descurajează deplasarea rapidă într-un mod dezorganizat. Te ajută să te deplasezi rapid pe termen lung în mai multe proiecte cu diverși colaboratori. ### Comiterile convenționale ar putea determina dezvoltatorii să limiteze tipul de comiteri pe care le fac, deoarece se vor gândi la tipurile furnizate? Comiterile convenționale ne încurajează să facem mai multe anumite tipuri de comiteri, cum ar fi remedieri. În afară de asta, flexibilitatea Comiterilor convenționale permite echipei tale să creeze propriile tipuri și să le schimbe în timp. ### Cum se leagă acest lucru de SemVer? Comiterile de tip `fix` ar trebui traduse în versiuni `PATCH`. Comiterile de tip `feat` ar trebui traduse în versiuni `MINOR`. Comiterile cu `BREAKING CHANGE` în comitri, indiferent de tip, ar trebui traduse în versiuni `MAJOR`. ### Cum ar trebui să numerotez extensiile mele conform specificației de Comiteri convenționale, de ex. `@jameswomack/conventional-commit-spec`? Îți recomandăm să utilizezi SemVer pentru a-ți lansa propriile extensii conform acestei specificații (și te încurajăm să faci aceste extensii!) ### Ce fac dacă folosesc accidental tipul de comitere greșit? #### Când ai folosit un tip care corespunde specificațiilor, dar nu este cel corect, de ex. `fix` în loc de `feat` Înainte de îmbinare sau lansare a greșelii, îți recomandăm să folosești `git rebase -i` pentru a edita istoricul de comitere. După lansare, curățarea va fi diferită în funcție de instrumentele și procesele pe care le utilizezi. #### Când ai folosit un tip _din afara_ specificației, de ex. `feet` în loc de `feat` În cel mai rău caz, nu este sfârșitul lumii dacă aterizează o comitere care nu îndeplinește specificația Comiteri convenționale. Înseamnă pur și simplu că acea comiterea va fi ratată de instrumentele care se bazează pe specificații. ### Trebuie ca toți colaboratorii mei să folosească specificația Comiteri convenționale? Nu! Dacă pe Git utilizezi un flux de lucru bazat pe îmbinare, întreținătorii potențiali pot curăța mesajele de comitere pe măsură ce sunt îmbinate, neadăugând vreo sarcină de lucru pentru cei care fac comiteri ocazional. Un flux de lucru obișnuit pentru aceasta este ca sistemul tău git să îmbine automat comiterile dintr-o cerere de extragere și să prezinte un formular pentru ca întreținătorul principal să introducă mesajul de comitere git corespunzător pentru îmbinare. ### Cum sunt gestionate comiterile de revenire de către Comiterile convenționale? Revenirea codului poate fi complicată: revii la mai multe comiteri? dacă revii la o funcționalitate, următoarea versiune ar trebui să fie în schimb un patch? Comiterile convenționale nu depun un efort explicit pentru a defini comportamentul invers. În schimb, lăsăm la latitudinea autorilor de instrumente să folosească flexibilitatea _tipurilor_ și _subsolurilor_ pentru a-și dezvolta logica pentru gestionarea reversurilor. O recomandare este să folosești tipul `revert` și un subsol care face referire la SHA-urile de comitere care sunt inversate: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.ru.md ================================================ --- draft: false aliases: ["/ru/"] --- # Соглашение о коммитах 1.0.0 ## Главное Спецификация «Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Она описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов. Данное соглашение совместимо с [Семантическим Версионированием](https://semver.org/lang/ru/), описывая новые функции, исправления и изменения, нарушающие обратную совместимость в сообщениях коммитов. Сообщения коммитов должны быть следующей структуры: --- ``` <тип>[необязательный контекст]: <описание> [необязательное тело] [необязательная(ые) сноска(и)] ``` ---
Коммит содержит следующие структурные элементы для передачи намерений пользователям вашей библиотеки: 1. **fix:** коммит _типа_ `fix` исправляет баг в вашем коде (соответствует [`PATCH`](https://semver.org/lang/ru/#%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%BE) в Cемантическом Версионировании). 1. **feat:** коммит _типа_ `feat` добавляет новую функцию в ваш код (соответствует [`MINOR`](https://semver.org/lang/ru/#%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%BE) в Cемантическом Версионировании). 1. **BREAKING CHANGE:** коммит, который имеет _сноску_ `BREAKING CHANGE` или коммит, заканчивающийся восклицательным знаком (`!`) после _типа_ или _контекста_, вводящий изменение(я), нарушающие обратную совместимость (соответствует [`MAJOR`](https://semver.org/lang/ru/#%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%BE) в Cемантическом Версионировании). `BREAKING CHANGE` может быть частью коммита любого _типа_. 1. Другие _типы_ коммитов разрешены. Например, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (основан на [соглашении Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рекомендует `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test` и другие. 1. Другие _сноски_ коммитов могут быть аналогичны соглашению [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Дополнительные _типы_ не требуются «Соглашению о коммитах» и не имеют неявного эффекта в семантическом версионировании (если только они не включают `BREAKING CHANGE`).

_Контекст_ может быть добавлен к _типу_ коммита, чтобы предоставить дополнительную контекстную информацию; она содержится в скобках. Например, `feat(parser): add ability to parse arrays`. ## Примеры ### Сообщение коммита с _описанием_ и _сноской_ `BREAKING CHANGE` ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Сообщение коммита с `!` для привлечения внимания к `BREAKING CHANGE` ``` feat!: send an email to the customer when a product is shipped ``` ### Сообщение коммита с _контекстом_ и `!` для привлечения внимания к `BREAKING CHANGE` ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Сообщение коммита вместе с `!` и _сноской_ `BREAKING CHANGE` ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Сообщение коммита без _тела_ ``` docs: correct spelling of CHANGELOG ``` ### Сообщение коммита с _контекстом_ ``` feat(lang): add polish language ``` ### Сообщение коммита с _телом_ из нескольких абзацев и несколькими _сносками_ ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Спецификация Слова «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» в данном документе должны интерпретироваться как в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Коммиты должны (MUST) начинается с _типа_, который является существительным: `feat`, `fix` и т.д. За ним следует необязательный (OPTIONAL) _контекст_, необязательный (OPTIONAL) восклицательный знак (`!`) и обязательные (REQUIRED) двоеточие (`:`) и пробел (` `). 1. _Тип_ `feat` должен (MUST) использоваться, когда коммит добавляет новый функционал в ваше приложение или вашу библиотеку. 1. _Тип_ `fix` должен (MUST) использоваться, когда коммит исправляет баг в вашем приложении или вашей библиотеке. 1. _Контекст_ может (MAY) следовать после _типа_. _Контекст_ должен (MUST) быть существительным, заключённым в круглые скобки, описывающий часть кодовой базы, которую затронул коммит. Например, `fix(parser)`. 1. _Описание_ должно (MUST) следовать сразу за двоеточием (`:`) и пробелом (` `) после _типа_ или _контекста_. _Описание_ представляет собой краткое изложение изменений кода. Например, `fix: array parsing issue when multiple spaces were contained in string`. 1. _Тело_ коммита может (MAY) следовать после короткого _описания_, добавляя дополнительную контекстную информацию об изменениях в коде. _Тело_ должно (MUST) отделяться от _описания_ одной пустой строкой. 1. _Тело_ коммита имеет произвольную форму и может (MAY) состоять из любого количества абзацев, разделённых новой строкой. 1. В одной или нескольких _сносках_ может (MAY) быть одна пустая строка после _тела_. Каждая _сноска_ должна (MUST) состоять из токена слова, за которым следует разделитель `:<пробел>` или `<пробел>#`, за которым следует строковое значение (основано на [git trailer format](https://git-scm.com/docs/git-interpret-trailers)). 1. Токен _сноски_ должен (MUST) использовать `-` вместо пробельных символов. Например, `Acked-by` (это помогает отличить раздел _сноски_ от его _тела_, состоящего из нескольких абзацев). Исключение составляет `BREAKING CHANGE`, которое может (MAY) также использоваться как токен. 1. _Сноска_ может (MAY) содержать пробелы и символы новой строки, а считывание должно (MUST) завершаться при обнаружении следующей допустимой пары токен-разделитель _сноски_. 1. Критические изменения должны (MUST) быть указаны в _типе_, _контексте_ или _сноске_ коммита. 1. Если `BREAKING CHANGE` включено в _сноску_, то оно должно (MUST) состоять из прописного текста `BREAKING CHANGE`, за которым следует двоеточие (`:`), пробел (` `) и _описание_. Например, `BREAKING CHANGE: environment variables now take precedence over config files`. 1. Если критические изменения находятся в _типе_ или _контексте_, то они должны (MUST) быть обозначены восклицательным знаком (`!`), непосредственно перед двоеточием (`:`). Если используется восклицательный знак (`!`), то `BREAKING CHANGE` может (MAY) быть опущен в _сноске_, а _описание_ коммита должно (SHALL) использоваться для описания критического изменения. 1. В ваших сообщениях коммитов могут (MAY) использоваться _типы_, отличные от `feat` и `fix`. Например, `docs: updated ref docs`. 1. Единицы информации, которые составляют «Соглашение о коммитах», не должны (MUST NOT) обрабатываться разработчиками как чувствительные к регистру, за исключением `BREAKING CHANGE`, которое должно (MUST) быть прописными. 1. `BREAKING-CHANGE` должен (MUST) быть синонимом `BREAKING CHANGE` при использовании в качестве токена в _сноске_. ## Зачем использовать «Соглашение о коммитах» * Автоматическое создание списков изменения. * Автоматическое определение семантического повышения версии (на основе _типов_ совершённых коммитов). * Информирование товарищей по команде, общественности и других заинтересованных сторон о характере изменений. * Запуск процессов сборки и публикации. * Упрощать людям участие в ваших проектах, позволив им изучить более структурированную историю коммитов. ## FAQ (часто задаваемые вопросы) ### Как мне поступать с сообщениями коммитов на начальном этапе разработки? Мы рекомендуем действовать так, как если бы вы уже выпустили продукт. Обычно *кто-то*, даже если это ваши коллеги-разработчики программного обеспечения, использует ваше программное обеспечение. Они захотят знать, что исправлено, что ломается и т. д. ### _Типы_ в заголовке коммита должны быть прописными или строчными? Выберите тот, который больше всего вам нравится, и строго ему следуйте. ### Что мне делать, если коммит соответствует более чем одному _типу_? По возможности вернитесь назад и сделайте несколько коммитов. Часть преимущества «Соглашения о коммитах» - его способность побуждать нас делать более организованные коммиты и PRs (pull requests, или запросы на вытягивание). ### Разве это не препятствует интенсивной разработке и быстрой итерации? Это препятствует быстрому неорганизованному движению. Это поможет вам быстро продвигаться в долгосрочной перспективе в нескольких проектах с разными участниками. ### Может ли «Соглашение о коммитах» привести разработчиков к ограничению _типов_ совершаемых ими коммитов, потому что они будут думать в соответствии с предоставленными _типами_? «Соглашение о коммитах» побуждает нас делать больше определённых _типов_ коммитов, таких, как `fix`. Помимо этого, гибкость «Соглашения о коммитах» позволяет вашей команде придумывать свои собственные _типы_ и со временем изменять их. ### Как это связано с Семантическим Версионированием? Коммиты _типа_ `fix` должны быть переведены в выпуски `PATCH`, `feat` — в `MINOR`, `BREAKING CHANGE`, независимо от _типа_, — в `MAJOR`. ### Как мне довести свои расширения до спецификации «Соглашение о коммитах». Например, `@jameswomack/standard-commit-spec`? Мы рекомендуем использовать Семантическое Версионирование для выпуска ваших собственных расширений для этой спецификации (и призываем вас создавать эти расширения!). ### Что мне делать, если я случайно использовал неправильный _тип_ коммита? #### Когда вы использовали неправильный _тип_, но соответствующий спецификации. Например, `fix` вместо `feat` Перед объединением или выпуском ошибки мы рекомендуем использовать `git rebase -i` для редактирования истории коммитов. После выпуска редактирование будет отличаться в зависимости от того, какие инструменты и процессы вы используете. #### Когда вы использовали _тип_, не указанный в спецификации. Например, `feet` вместо `feat` В худшем случае это ещё не конец света, если коммит не соответствует спецификации «Соглашения о коммитах». Это просто означает, что коммит будет пропущен инструментами, основанными на спецификации. ### Все ли мои участники должны использовать спецификацию «Соглашения о коммитах»? Нет! Если вы используете рабочий процесс на основе соединения (squash) коммитов в Git, то ведущие специалисты по сопровождению могут приводить в порядок сообщения коммитов по мере их слияния (merge), не добавляя нагрузки для обычных коммиттеров. Обычный рабочий процесс для этого состоит в том, чтобы ваша система Git автоматически соединяла коммиты из PR и представляла форму для ведущего сопровождающего, чтобы ввести более подходящее сообщение коммита для слияния. ### Как «Соглашение о коммитах» обрабатывает отмену коммитов? Отмена изменений кода может быть сложной: - Вы отменяете изменения нескольких коммитов? - Если вы отмените изменения новых функций, должен ли следующий выпуск быть патчем? «Соглашение о коммитах» не делает явных попыток определить поведение отмены изменений. Вместо этого мы оставляем авторам инструментов использование гибкости _типов_ и _сносок_ для разработки своей логики для обработки отмены изменений. Одна из рекомендаций — использовать _тип_ `revert` и _сноску_, которая ссылается на отменяемые хэш-суммы коммитов. Например: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.si.md ================================================ --- draft: false aliases: ["/si/"] --- # සම්මුතිවාදී කමිට්ස් (Conventional Commits) 1.0.0 ## සාරාංශය සම්මුතිවාදී කමිට් (Conventional Commits) පිරිවිතරය යනු කමිට් පණිවිඩ (commit messages) සඳහා වන සැහැල්ලු සම්මුතියකි. එය පැහැදිලි කමිට් ඉතිහාසයක් (commit history) නිර්මාණය කිරීම සඳහා සරල නීති මාලාවක් සපයයි; එමඟින් ස්වයංක්‍රීය මෙවලම් (automated tools) නිර්මාණය කිරීම පහසු කරයි. මෙම සම්මුතිය SemVer සමඟ මනාව ගැලපෙන අතර, කමිට් පණිවිඩ මගින් සිදු කරන ලද විශේෂාංග (features), නිවැරදි කිරීම් (fixes) සහ බිඳවැටීම් වෙනස්කම් (breaking changes) විස්තර කරයි. කමිට් පණිවිඩය පහත පරිදි ව්‍යුහගත කළ යුතුය: ``` <වර්ගය>[විකල්ප විෂය පථය]: <විස්තරය> [විකල්ප ප්‍රධාන කොටස] [විකල්ප පාදකය(න්)] ``` ඔබේ මෘදුකාංග පුස්තකාලය භාවිතා කරන්නන්ට අදහස සන්නිවේදනය කිරීම සඳහා කමිට් පණිවිඩය පහත සඳහන් ව්‍යුහාත්මක අංග අඩංගු විය යුතුය: 1. **fix:** 'fix' වර්ගයේ කමිට් එකක් මගින් ඔබේ කේත පද්ධතියේ පවතින දෝෂයක් නිවැරදි කිරීමක් පෙන්නුම් කරයි (මෙය Semantic Versioning හි 'PATCH' සමඟ සම්බන්ධ වේ). 2. **feat:** 'feat' වර්ගයේ කමිට් එකක් මගින් කේත පද්ධතියට නව විශේෂාංගයක් හඳුන්වා දීම පෙන්නුම් කරයි (මෙය Semantic Versioning හි 'MINOR' සමඟ සම්බන්ධ වේ). 3. **BREAKING CHANGE:** පාදකයේ (footer) `BREAKING CHANGE:` ලෙස සඳහන් වන, හෝ වර්ගය/විෂය පථය අවසානයේ `!` ලකුණ ඇතුළත් වන කමිට් එකක් මගින් මෘදුකාංගයේ අතුරුමුහුණතේ (API) බිඳවැටීමක් හෙවත් විශාල වෙනසක් පෙන්නුම් කරයි (මෙය Semantic Versioning හි 'MAJOR' සමඟ සම්බන්ධ වේ). ඕනෑම වර්ගයක කමිට් එකක BREAKING CHANGE එකක් අඩංගු විය හැක. 4. **fix:** සහ **feat:** හැර වෙනත් වර්ග සඳහාද අවසර ඇත, උදාහරණයක් ලෙස `@commitlint/config-conventional` (Angular සම්මුතිය මත පදනම් වූ) විසින් **build:**, **chore:**, **ci:**, **docs:**, **style:**, **refactor:**, **perf:**, **test:**, සහ අනෙකුත් වර්ග නිර්දේශ කරයි. 5. **BREAKING CHANGE: <විස්තරය>** හැර වෙනත් පාදකයන් (footers) ද සැපයිය හැකි අතර ඒවා git trailer ආකෘතියට සමාන සම්මුතියක් අනුගමනය කරයි. අතිරේක වර්ග සම්මුතිවාදී කමිට් පිරිවිතරය මගින් අනිවාර්ය නොකරන අතර, ඒවා Semantic Versioning කෙරෙහි ව්‍යංග බලපෑමක් ඇති නොකරයි (BREAKING CHANGE එකක් ඇතුළත් නොවේ නම්). කමිට් වර්ගයකට අමතර සන්දර්භීය තොරතුරු සැපයීම සඳහා වරහන් තුළ විෂය පථයක් (scope) ඇතුළත් කළ හැකිය, උදා: `feat(parser): add ability to parse arrays`. ## උදාහරණ ### විස්තරය සහ BREAKING CHANGE පාදකය සහිත කමිට් පණිවිඩය ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### බිඳවැටීමක් (breaking change) පිළිබඳ අවධානය යොමු කිරීමට `!` සහිත කමිට් පණිවිඩය ``` feat!: send an email to the customer when a product is shipped ``` ### විෂය පථය (scope) සහ `!` සහිත කමිට් පණිවිඩය ``` feat(api)!: send an email to the customer when a product is shipped ``` ### `!` සහ BREAKING CHANGE පාදකය යන දෙකම සහිත කමිට් පණිවිඩය ``` chore!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### ප්‍රධාන කොටසක් (body) නොමැති කමිට් පණිවිඩය ``` docs: correct spelling of CHANGELOG ``` ### විෂය පථය සහිත කමිට් පණිවිඩය ``` feat(lang): add Sinhala language ``` ### ඡේද කිහිපයකින් යුත් ප්‍රධාන කොටස සහ පාදකයන් කිහිපයක් සහිත කමිට් පණිවිඩය ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## පිරිවිතරය (Specification) මෙම ලේඛනයේ ඇති "සිදු කළ යුතුය" (MUST), "සිදු නොකළ යුතුය" (MUST NOT), "අවශ්‍ය වේ" (REQUIRED), "කළ යුතුය" (SHALL), "නොකළ යුතුය" (SHALL NOT), "කළ යුත්තේය" (SHOULD), "නොකළ යුත්තේය" (SHOULD NOT), "නිර්දේශිතයි" (RECOMMENDED), "හැකිය" (MAY), සහ "විකල්ප වේ" (OPTIONAL) යන වචන RFC 2119 හි විස්තර කර ඇති පරිදි අර්ථකථනය කළ යුතුය. 1. කමිට් සඳහා වර්ගයක් (type) උපසර්ගයක් ලෙස තිබිය යුතුය. එය නාම පදයක් විය යුතුය (feat, fix, ආදී), ඉන්පසුව විකල්ප විෂය පථයක් (scope), විකල්ප `!` ලකුණක් සහ අනිවාර්යයෙන් තිතක් (colon) සහ හිස්තැනක් (space) තිබිය යුතුය. 2. ඔබේ යෙදුමට හෝ පුස්තකාලයට නව විශේෂාංගයක් එක් කරන විට `feat` වර්ගය භාවිතා කළ යුතුය. 3. ඔබේ යෙදුමේ පවතින දෝෂයක් නිවැරදි කරන විට `fix` වර්ගය භාවිතා කළ යුතුය. 4. වර්ගයකට පසුව විෂය පථයක් (scope) සැපයිය හැකිය. විෂය පථයක් යනු කේත පද්ධතියේ නිශ්චිත කොටසක් විස්තර කරන නාම පදයක් විය යුතු අතර එය වරහන් වලින් වට විය යුතුය, උදා: `fix(parser):` 5. වර්ගය/විෂය පථය උපසර්ගයට පසුව ඇති තිත සහ හිස්තැනට පසුව විස්තරයක් (description) අනිවාර්යයෙන්ම තිබිය යුතුය. විස්තරය යනු කේත වෙනස්කම් පිළිබඳ කෙටි සාරාංශයකි, උදා: `fix: array parsing issue when multiple spaces were contained in string.` 6. කෙටි විස්තරයට පසුව, කේත වෙනස්කම් පිළිබඳ අමතර තොරතුරු සැපයීම සඳහා දිගු කමිට් ප්‍රධාන කොටසක් (body) සැපයිය හැකිය. ප්‍රධාන කොටස විස්තරයට පසුව එක් හිස් පේළියකින් පසුව ආරම්භ විය යුතුය. 7. කමිට් ප්‍රධාන කොටස ඕනෑම ආකාරයක විය හැකි අතර නව පේළි වලින් වෙන් කරන ලද ඡේද ගණනාවකින් සමන්විත විය හැකිය. 8. ප්‍රධාන කොටසට පසුව එක් හිස් පේළියකින් පසුව පාදක (footers) එකක් හෝ කිහිපයක් සැපයිය හැකිය. සෑම පාදකයක්ම වචන ටෝකනයකින් සමන්විත විය යුතු අතර, ඉන් පසුව `:` හෝ `#` බෙදුම්කාරකය සහ පසුව අගයක් තිබිය යුතුය (මෙය git trailer සම්මුතියෙන් ආභාසය ලබා ඇත). 9. පාදකයක ටෝකනය සඳහා හිස්තැන් වෙනුවට `-` භාවිතා කළ යුතුය, උදා: `Acked-by` (මෙය බහු-ඡේද ප්‍රධාන කොටසකින් පාදක කොටස වෙන්කර හඳුනා ගැනීමට උපකාරී වේ). `BREAKING CHANGE` සඳහා මෙහිදී ව්‍යතිරේකයක් පවතී, එය ටෝකනයක් ලෙසද භාවිතා කළ හැක. 10. පාදකයක අගයෙහි හිස්තැන් සහ නව පේළි තිබිය හැකි අතර, මීළඟ නිවැරදි පාදක ටෝකනය/බෙදුම්කාරක යුගලය හමු වූ විට විග්‍රහ කිරීම (parsing) අවසන් විය යුතුය. 11. බිඳවැටීම් වෙනස්කම් (Breaking changes) කමිට් එකක වර්ගය/විෂය පථය උපසර්ගයෙහි හෝ පාදකයේ ඇතුළත් කළ යුතුය. 12. පාදකයක ඇතුළත් කරන්නේ නම්, බිඳවැටීම් වෙනස්කම `BREAKING CHANGE` යන ලොකු අකුරු සහිත පෙළින් ආරම්භ විය යුතු අතර, ඉන් පසුව තිතක්, හිස්තැනක් සහ විස්තරයක් තිබිය යුතුය. උදා: `BREAKING CHANGE: environment variables now take precedence over config files.` 13. වර්ගය/විෂය පථය උපසර්ගයෙහි ඇතුළත් කරන්නේ නම්, බිඳවැටීම් වෙනස්කම් `:` ට පෙර වහාම `!` ලකුණින් දැක්විය යුතුය. `!` භාවිතා කරන්නේ නම්, පාදක කොටසින් `BREAKING CHANGE:` මඟ හැරිය හැකි අතර, බිඳවැටීම විස්තර කිරීමට කමිට් විස්තරය භාවිතා කළ යුතුය. 14. ඔබේ කමිට් පණිවිඩවල `feat` සහ `fix` හැර වෙනත් වර්ග ද භාවිතා කළ හැකිය, උදා: `docs: update ref docs.` 15. සම්මුතිවාදී කමිට් වල අඩංගු තොරතුරු ඒකක, ක්‍රියාත්මක කරන්නන් විසින් අකුරු ප්‍රමාණය (case sensitive) සලකා නොබැලිය යුතුය, නමුත් `BREAKING CHANGE` සෑම විටම ලොකු අකුරින් තිබිය යුතුය. 16. පාදකයක ටෝකනයක් ලෙස භාවිතා කරන විට `BREAKING-CHANGE` යන්න `BREAKING CHANGE` සඳහා සමාන පදයක් විය යුතුය. ## සම්මුතිවාදී කමිට්ස් භාවිතා කරන්නේ ඇයි? * CHANGELOG ස්වයංක්‍රීයව ජනනය කිරීම සඳහා. * කමිට් වර්ග මත පදනම්ව Semantic Version (SemVer) අගය වැඩි කිරීම (bump) ස්වයංක්‍රීයව තීරණය කිරීම සඳහා. * කණ්ඩායම් සාමාජිකයින්ට, පොදු ජනයාට සහ අනෙකුත් පාර්ශවකරුවන්ට වෙනස්කම්වල ස්වභාවය සන්නිවේදනය කිරීම සඳහා. * Build සහ publish ක්‍රියාවලීන් ක්‍රියාත්මක කිරීම සඳහා. * ව්‍යුහගත කමිට් ඉතිහාසයක් මඟින් මිනිසුන්ට ඔබේ ව්‍යාපෘති සඳහා දායක වීම පහසු කිරීම සඳහා. ## නිතර අසනු ලබන ප්‍රශ්න (FAQ) ### ආරම්භක සංවර්ධන අවධියේදී (initial development phase) මම කමිට් පණිවිඩ හැසිරවිය යුත්තේ කෙසේද? ඔබ දැනටමත් නිෂ්පාදනය නිකුත් කර ඇති පරිදි කටයුතු කරන ලෙස අපි නිර්දේශ කරමු. සාමාන්‍යයෙන් කවුරුන් හෝ (ඔබේ සම-සංවර්ධකයින් වුවද) ඔබේ මෘදුකාංගය භාවිතා කරයි. ඔවුන්ට මොනවාද නිවැරදි කර ඇත්තේ, මොනවාද බිඳී ඇත්තේ යන්න දැන ගැනීමට අවශ්‍ය වනු ඇත. ### කමිට් මාතෘකාවේ වර්ග ලොකු අකුරින්ද නැත්නම් කුඩා අකුරින්ද තිබිය යුතුද? ඕනෑම ආකාරයක් භාවිතා කළ හැක, නමුත් ස්ථාවරව (consistent) එකම ආකාරයක් භාවිතා කිරීම වඩාත් සුදුසුය. ### කමිට් එක වර්ග එකකට වඩා වැඩි ගණනකට ගැලපේ නම් මා කුමක් කළ යුතුද? හැකි සෑම විටම ආපසු ගොස් කමිට් කිහිපයක් සාදන්න. සම්මුතිවාදී කමිට් වල එක් ප්‍රයෝජනයක් වන්නේ වඩාත් සංවිධානාත්මක කමිට් සහ PR නිර්මාණය කිරීමට අපව යොමු කිරීමයි. ### මෙය වේගවත් සංවර්ධනයට සහ වේගවත් පුනරාවර්තනයට බාධාවක් නොවේද? එය අසංවිධානාත්මක ලෙස වේගයෙන් ගමන් කිරීම අධෛර්යමත් කරයි. විවිධ දායකයින් සිටින ව්‍යාපෘති කිහිපයක දිගුකාලීනව වේගයෙන් ගමන් කිරීමට මෙය ඔබට උපකාරී වේ. ### ලබා දී ඇති වර්ග ගැන සිතීම නිසා සංවර්ධකයින් කරන කමිට් වර්ග සීමා වීමට සම්මුතිවාදී කමිට්ස් හේතු විය හැකිද? සම්මුතිවාදී කමිට්ස් මඟින් 'fixes' වැනි ඇතැම් වර්ගවල කමිට් වැඩිපුර කිරීමට අපව දිරිමත් කරයි. එය හැරුණු විට, සම්මුතිවාදී කමිට් වල නම්‍යශීලීභාවය නිසා ඔබේ කණ්ඩායමට තමන්ගේම වර්ග නිර්මාණය කිරීමට සහ කාලයත් සමඟ ඒවා වෙනස් කිරීමට ඉඩ සලසයි. ### මෙය SemVer සමඟ සම්බන්ධ වන්නේ කෙසේද? * `fix` වර්ගයේ කමිට් `PATCH` නිකුත් කිරීම් ලෙස පරිවර්තනය කළ යුතුය. * `feat` වර්ගයේ කමිට් `MINOR` නිකුත් කිරීම් ලෙස පරිවර්තනය කළ යුතුය. * කමිට් වර්ගය කුමක් වුවත් `BREAKING CHANGE` සහිත කමිට් `MAJOR` නිකුත් කිරීම් ලෙස පරිවර්තනය කළ යුතුය. ### සම්මුතිවාදී කමිට් පිරිවිතරයට මා කරන දිගු කිරීම් (extensions) සඳහා අනුවාද (versioning) ලබා දිය යුත්තේ කෙසේද? උදා: `@jameswomack/conventional-commit-spec` ඔබේම දිගු කිරීම් නිකුත් කිරීම සඳහා SemVer භාවිතා කරන ලෙස අපි නිර්දේශ කරමු (තවද මෙම දිගු කිරීම් කිරීමට අපි ඔබව දිරිමත් කරමු!). ### මම අහම්බෙන් වැරදි කමිට් වර්ගයක් භාවිතා කළහොත් මා කුමක් කළ යුතුද? #### පිරිවිතරයේ පවතින නමුත් වැරදි වර්ගයක් භාවිතා කළ විට (උදා: feat වෙනුවට fix) එම වැරැද්ද ඒකාබද්ධ කිරීමට (merge) හෝ නිකුත් කිරීමට පෙර, කමිට් ඉතිහාසය සංස්කරණය කිරීමට `git rebase -i` භාවිතා කරන ලෙස අපි නිර්දේශ කරමු. නිකුත් කිරීමෙන් පසුව, ඔබ භාවිතා කරන මෙවලම් සහ ක්‍රියාවලීන් අනුව පිරිසිදු කිරීම වෙනස් වනු ඇත. #### පිරිවිතරයේ නොමැති වර්ගයක් භාවිතා කළ විට (උදා: feat වෙනුවට feet) නරකම අවස්ථාවක, සම්මුතිවාදී කමිට් පිරිවිතරයට නොගැලපෙන කමිට් එකක් ඇතුළත් වීම ලෝක අවසානය නොවේ. එයින් අදහස් වන්නේ එම කමිට් එක පිරිවිතරය මත පදනම් වූ මෙවලම් වලට මඟ හැරෙනු ඇති බවයි. ### මගේ සියලුම දායකයින් (contributors) සම්මුතිවාදී කමිට් පිරිවිතරය භාවිතා කළ යුතුද? නැත! ඔබ Git හි squash මත පදනම් වූ කාර්ය ප්‍රවාහයක් භාවිතා කරන්නේ නම්, ප්‍රධාන නඩත්තු කරන්නන්ට (maintainers) කමිට් ඒකාබද්ධ කිරීමේදී පණිවිඩ පිරිසිදු කළ හැකිය—එමඟින් සාමාන්‍ය දායකයින්ට අමතර වැඩ කොටසක් එක් නොවේ. මෙහි පොදු කාර්ය ප්‍රවාහයක් වන්නේ pull request එකකින් එන කමිට් ස්වයංක්‍රීයව squash කිරීමට සැලැස්වීම සහ නඩත්තු කරන්නාට නිසි කමිට් පණිවිඩය ඇතුළත් කිරීමට පෝරමයක් ලබා දීමයි. ### සම්මුතිවාදී කමිට්ස් 'revert' කමිට් හසුරුවන්නේ කෙසේද? කේතය පෙර තත්වයට පත් කිරීම (Reverting) සංකීර්ණ විය හැකිය: ඔබ කමිට් කිහිපයක් පෙර තත්වයට පත් කරනවාද? ඔබ විශේෂාංගයක් පෙර තත්වයට පත් කරන්නේ නම්, ඊළඟ නිකුතුව patch එකක් විය යුතුද? සම්මුතිවාදී කමිට්ස් මඟින් revert හැසිරීම අර්ථ දැක්වීමට නිශ්චිත උත්සාහයක් නොගනී. ඒ වෙනුවට, revert හැසිරවීම සඳහා ඔවුන්ගේම තර්කනය වර්ධනය කර ගැනීමට වර්ග සහ පාදකවල නම්‍යශීලීභාවය භාවිතා කිරීමට මෙවලම් කතුවරුන්ට අපි ඉඩ දෙමු. එක් නිර්දේශයක් වන්නේ `revert` වර්ගය සහ පෙර තත්වයට පත් කරන කමිට් වල SHA අගයන් සඳහන් කරන පාදකයක් භාවිතා කිරීමයි: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.sr.md ================================================ --- draft: false aliases: ["/sr/"] --- # Conventional Commits 1.0.0 ## Summary Specifikacija Conventional Commits predstavlja laganu konvenciju zasnovanu na porukama commit-ova. Ona obezbeđuje jednostavan skup pravila za kreiranje eksplicitne istorije commit-ova, što olakšava pisanje automatizovanih alata iznad nje. Ova konvencija se prirodno uklapa sa [SemVer-om](http://semver.org), jer opisuje funkcionalnosti, ispravke i ključne promene uvedene u commit porukama. Poruka commita treba da bude strukturirana na sledeći način: --- ``` [optional scope]: [optional body] [optional footer(s)] ``` ---
Commit sadrži sledeće strukturalne elemente, kako bi se jasno komunicirala namera korisnicima vaše biblioteke: 1. **fix:** commit _tipa_ `fix` ispravlja grešku u vašoj bazi koda (odgovara [`PATCH`](http://semver.org/#summary) nivou u Semantic Versioning-u). 2. **feat:** commit _tipa_ `feat` uvodi novu funkcionalnost u kod (odgovara [`MINOR`](http://semver.org/#summary) nivou u Semantic Versioning-u). 3. **BREAKING CHANGE:** commit koji ima fusnotu `BREAKING CHANGE:`, ili dodaje znak `!` nakon type/scope segmenta, uvodi „breaking“ promenu API-ja (odgovara [`MAJOR`](http://semver.org/#summary) nivou u Semantic Versioning-u). BREAKING CHANGE može postojati u commit-ovima bilo kog _tipa_. 4. _tipovi_ osim `fix:` i `feat:` su dozvoljeni; na primer [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (baziran na [Angular konvenciji](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) preporučuje tipove `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, itd. 5. _fusnote_ osim `BREAKING CHANGE: ` su dozvoljene i slede konvenciju sličnu [git trailer formatu](https://git-scm.com/docs/git-interpret-trailers). Dodatni tipovi nisu obavezni po ovoj specifikaciji i nemaju implicitno značenje u Semantic Versioning-u (osim ako sadrže BREAKING CHANGE).

Opciona oblast (scope) može biti dodata tipu commit-a kako bi pružila dodatni kontekst, i piše se u zagradi, npr.: `feat(parser): add ability to parse arrays`. ## Primeri ### Commit sa opisom i BREAKING CHANGE fusnotom ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit poruka sa `!` znakom koji ukazuje na breaking promenu ``` feat!: send an email to the customer when a product is shipped ``` ### Commit poruka sa scope-om i `!` znakom ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Commit poruka sa `!` znakom i BREAKING CHANGE fusnotom ``` chore!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Commit poruka bez tela poruke ``` docs: correct spelling of CHANGELOG ``` ### Commit poruka sa scope-om ``` feat(lang): add Serbian language ``` ### Commit poruka sa multi-paragraf telom i više fusnota ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specifikacija Ključne reči “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” i “OPTIONAL” u ovom dokumentu tumače se u skladu sa [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commit-ovi MORAJU imati prefiks tipa (imenica), kao što su `feat`, `fix` itd., opcionim scope-om, opcionim `!`, i obaveznim dvotačkom i razmakom nakon toga. 2. Tip `feat` se MORA koristiti kada commit dodaje novu funkcionalnost. 3. Tip `fix` se MORA koristiti kada commit ispravlja grešku. 4. Scope MOŽE biti dodat posle tipa. Scope MORA biti imenica koja opisuje deo kodne baze i mora biti u zagradi, npr. `fix(parser):` 5. Opis MORA odmah slediti posle dvotačke i razmaka. Opis je kratak rezime promena koda npr.: _fix: array parsing issue when multiple spaces were contained in string_. 6. Duže telo commit-a MOŽE biti dato posle opisa, pružajući dodatne kontekstualne informacije o promenama koda. Telo MORA početi posle jednog praznog reda. 7. Telo commit-a je slobodnog formata i može sadržati proizvoljan broj pasusa. 8. Jedna ili više fusnota MOŽE biti dodata posle još jednog praznog reda. Svaka fusnota MORA imati token, zatim `:` ili `#`, pa vrednost stringa (inspirisano od strane [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 9. Token fusnota MORA koristiti crticu `-` umesto razmaka, npr., `Acked-by` (ovo pomaže u razlikovanju fusnota od tela koje se sastoji od više pasusa). Izuzetak je napravljen za `BREAKING CHANGE`, koji se takođe MOŽE koristiti kao token. 10. Vrednost fusnote MOŽE sadržati razmake i nove redove; parsiranje MORA da se završi kada se primeti sledeći važeći par tokena/separatora u fusnoti. 11. Breaking promene MORAJU biti naznačene u type/scope prefiksu ili kao fusnota. 12. Ako je uključena kao fusnota, ključna promena MORA da sadrži tekst napisan velikim slovima BREAKING CHANGE, nakon čega slede dvotačka, razmak i opis, npr. _BREAKING CHANGE: environment variables now take precedence over config files_. 13. Ako je u prefiksu (type/scope), ključne izmene MORAJU biti označene znakom `!` pre dvotačke `:`. Ako se koristi znak `!`, MOŽE se izostaviti `BREAKING CHANGE` iz fusnote, a opis izmene se MORA koristiti za opis ključne izmene. 14. Tipovi koji nisu `feat` i `fix` MOGU se koristiti u vašim commit porukama, npr. _docs: update ref docs._ 15. Jedinice informacija koje čine konvencionalne commit-ove NE SMEJU biti tretirane kao osetljive na velika i mala slova od strane implementatora, sa izuzetkom BREAKING CHANGE koje MORA biti velikim slovima. 16. BREAKING-CHANGE MORA biti sinonim za BREAKING CHANGE, kada se koristi kao token u fusnoti. ## Zašto koristiti Conventional Commits * Automatsko generisanje CHANGELOG-ova * Automatsko određivanje semantičke nadogradnje verzije (na osnovu tipova commit-a). * Saopštavanje promena kolegama, javnosti i drugim zainteresovanim stranama. * Okidanje build i publish procesa * Olakšava doprinos novim saradnicima i održava organizovan commit istorijat. ## Česta pitanja (FAQ) ### Kako da pristupim commit porukama u ranoj fazi razvoja? Preporučujemo da se ponašate kao da je proizvod već objavljen. Neko već koristi vaš softver i želi da zna šta je ispravljeno i šta se menja. ### Da li tip commit-a u naslovu treba da bude malim ili velikim slovima? Može bilo kako, ali je najbolje biti dosledan. ### Šta da radim ako commit odgovara više od jednog tipa commit-a? Vratite se i napravite višestruke commit-ove kad god je to moguće. Deo prednosti Conventional Commits je njihova sposobnost da nas podstaknu da pravimo organizovanije commit-ove i PR-eve. ### Da li ovo usporava razvoj? Sprečava samo haotično kretanje. Dugoročno ubrzava rad na više projekata sa različitim timovima. ### Da li ovo ograničava programere u izboru tipova? Conventional Commits nas podstiče da pravimo više određenih vrsta commit-ova, kao što su ispravke. Osim toga, fleksibilnost Conventional Commits omogućava vašem timu da osmisli sopstvene tipove i da ih menja tokom vremena. ### Kako se ovo odnosi na SemVer? Commit-ovi tipa `fix` treba da se prevedu na izdanja `PATCH`. Commit-ovi tipa `feat` treba da se prevedu na izdanja `MINOR`. Commit-ovi sa `BREAKING CHANGE` u commit-u, bez obzira na tip, treba da se prevedu na izdanja `MAJOR`. ### Kako treba da verzionišem svoje ekstenzije prema specifikaciji Conventional Commits-a, npr. `@jameswomack/conventional-commit-spec`? Preporučujemo korišćenje SemVer-a za objavljivanje sopstvenih ekstenzija prema ovoj specifikaciji (i ohrabrujemo vas da ih napravite!). ### Šta da radim ako slučajno koristim pogrešan tip commit-a? #### Kada ste koristili tip koji je iz specifikacije, ali nije ispravan tip, npr. `fix` umesto `feat` Pre merge-a ili objavljivanja greške, preporučujemo da koristite `git rebase -i` za uređivanje istorije izmena. Nakon objavljivanja, čišćenje će biti drugačije u zavisnosti od alata i procesa koje koristite. #### Kada ste koristili tip koji *nije* iz specifikacije, npr. `feet` umesto `feat` U najgorem slučaju, nije kraj sveta ako se commit završi tako što ne ispunjava specifikaciju Conventional Commits-a. To jednostavno znači da će alati zasnovani na toj specifikaciji propustiti taj commit. ### Da li svi moji saradnici moraju da koriste specifikaciju konvencionalnih commit-a? Ne! Ako koristite tok rada zasnovan na squash-u na Git-u, glavni održavaoci mogu da očiste poruke o commit-ovima dok se merge-uju - bez dodatnog opterećenja za povremene korisnike. Uobičajeni tok rada za ovo je da vaš Git sistem automatski squash-uje commit-ove iz zahteva za pull i predstavi obrazac glavnom održavaocu da unese odgovarajuću Git poruku o commit-ovima za merge. ### Kako Conventional Commits postupaju sa vraćanjem izmena? Vraćanje koda može biti komplikovano: da li vraćate više izmena (commit)? Ako vraćate funkciju, da li bi sledeće izdanje trebalo da bude zakrpa (patch)? Conventional Commits ne pokušava izričito da definiše ponašanje prilikom vraćanja izmena (revert). Umesto toga, prepuštamo autorima alata da iskoriste fleksibilnost _types_ i _footers_ kako bi razvili sopstvenu logiku za rukovanje vraćanjem commit‑ova. Jedna od preporuka je da se koristi tip `revert` i fusnota koji referencira SHA oznake commit‑ova koji se vraćaju: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.ta.md ================================================ --- draft: false aliases: ["/ta/"] --- # வழக்கமான கமிட்கள் 1.0.0 ## Summary ### சுருக்கம் வழக்கமான கமிட்கள் விவரக்குறிப்பு என்பது கமிட் செய்திகளுக்கு மேல் ஒரு இலகுரக மரபு ஆகும். இது வெளிப்படையான கமிட் வரலாற்றை உருவாக்குவதற்கான எளிதான விதிகளின் தொகுப்பை வழங்குகிறது; இது மேலே தானியங்கி கருவிகளை எழுதுவதை எளிதாக்குகிறது. இந்த மாநாடு கமிட் செய்திகளில் செய்யப்பட்ட அம்சங்கள், திருத்தங்கள் மற்றும் முறிவு மாற்றங்களை விவரிப்பதன் மூலம் [SemVer](http://semver.org) உடன் ஒத்துப்போகிறது. கமிட் செய்தி பின்வருமாறு கட்டமைக்கப்பட வேண்டும்: --- ``` [உங்கள் விருப்பத்தேர்வு நோக்கம்]: [உங்கள் விருப்ப உள்ளடக்கம்] [உங்கள் விருப்ப தலைப்பு(கள்)] ``` ---
உங்கள் நூலகத்தின் நுகர்வோருக்கு நோக்கத்தைத் தெரிவிக்க, கமிட்டில் பின்வரும் கட்டமைப்பு கூறுகள் உள்ளன: 1. **fix:** சரிசெய்தல்: _type_ `fix` இன் கமிட் உங்கள் குறியீட்டுத் தளத்தில் ஒரு பிழையைத் தடுக்கிறது (இது சொற்பொருள் பதிப்பில் [`PATCH`](http://semver.org/#summary) உடன் தொடர்புடையது). 1. **feat:** _type_ `feat` இன் கமிட் குறியீட்டுத் தளத்தில் ஒரு புதிய அம்சத்தை அறிமுகப்படுத்துகிறது (இது சொற்பொருள் பதிப்பில் [`MINOR`](http://semver.org/#summary) உடன் தொடர்புடையது). 1. **BREAKING CHANGE:** `BREAKING CHANGE:` என்ற அடிக்குறிப்பைக் கொண்ட ஒரு கமிட், அல்லது வகை/நோக்கத்திற்குப் பிறகு `!` ஐச் சேர்த்து, ஒரு பிரேக்கிங் API மாற்றத்தை அறிமுகப்படுத்துகிறது (சொற்பொருள் பதிப்பில் [`MAJOR`](http://semver.org/#summary) உடன் தொடர்புடையது). BREAKING CHANGE என்பது எந்த _type_ இன் கமிட்களின் ஒரு பகுதியாக இருக்கலாம். 1. `fix:` மற்றும் `feat:` தவிர மற்ற _types_ அனுமதிக்கப்படுகின்றன, எடுத்துக்காட்டாக [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) ([Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) அடிப்படையில்) `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` மற்றும் பிறவற்றைப் பரிந்துரைக்கிறது. 1. `BREAKING CHANGE: ` தவிர மற்ற _footers_ வழங்கப்படலாம் மற்றும் [git trailer format](https://git-scm.com/docs/git-interpret-trailers) இது போன்ற ஒரு மாநாட்டைப் பின்பற்றலாம். கூடுதல் வகைகள் வழக்கமான கமிட்கள் விவரக்குறிப்பால் கட்டாயப்படுத்தப்படவில்லை, மேலும் சொற்பொருள் பதிப்பில் எந்த மறைமுக விளைவையும் ஏற்படுத்தாது (அவை ஒரு BREAKING CHANGE ஐ உள்ளடக்கியிருந்தால் தவிர).

கூடுதல் சூழல் தகவல்களை வழங்க, ஒரு கமிட்டின் வகைக்கு ஒரு நோக்கம் வழங்கப்படலாம் மற்றும் அடைப்புக்குறிக்குள் உள்ளது, எ.கா., `feat(parser): add ability to parse arrays`. ## எடுத்துக்காட்டுகள் ### ஒரு விளக்கத்துடன் கூடிய கமிட் செய்யவும் மற்றும் BREAKING CHANGE footer அடிக்குறிப்பையும் பயன்படுத்தவும் ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### breaking change-க்கு கவனத்தை ஈர்க்க `!` உடன் செய்தியை கமிட் செய்யவும் ``` feat!: send an email to the customer when a product is shipped ``` ### scope-உடன் செய்தியை கமிட் செய்யவும் மற்றும் BREAKING CHANGE கவனத்தை ஈர்க்க `!` ``` feat(api)!: send an email to the customer when a product is shipped ``` ### `!` மற்றும் BREAKING CHANGE footer இரண்டையும் கொண்டு கமிட் செய்தியை கமிட் செய்யவும் ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Body இல்லாத commit செய்தியை கமிட் செய்யவும் ``` docs: correct spelling of CHANGELOG ``` ### Scope மூலம் செய்தியை கமிட் செய்யவும் ``` feat(lang): add polish language ``` ### பல பத்தி உள்ளடக்கம் மற்றும் பல அடிக்குறிப்புகளுடன் செய்தியை கமிட் செய்யவும். ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Specification ### ஆவண விவரக்குறிப்பு இந்த ஆவணத்தில் உள்ள "கட்டாயம்" (“MUST”), அல்லது "கட்டாயம் இல்லை" (“MUST NOT”), "தேவை" (“REQUIRED”), அல்லது "வேண்டும்" (“SHALL”), "கூடாது" "(“SHALL NOT”), அல்லது "வேண்டும்" (“SHOULD”), "கூடாது" (“SHOULD NOT”), "பரிந்துரைக்கப்பட்டது" (“RECOMMENDS”), "இருக்கலாம்" ("MAY") மற்றும் "விருப்பத்தேர்வு" (“OPTIONAL”) ஆகிய முக்கிய வார்த்தைகள் [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) இல் விவரிக்கப்பட்டுள்ளபடி விளக்கப்பட வேண்டும். 1. கமிட்கள், `feat`, `fix`-க்கு போன்ற பெயர்ச்சொல்லைக் கொண்ட ஒரு வகையுடன் முன்னொட்டாகச் சேர்க்கப்பட வேண்டும், அதைத் தொடர்ந்து OPTIONAL scope, OPTIONAL `!`, மற்றும் தேவையான முனையப் பெருங்குடல் மற்றும் இடைவெளி இருக்க வேண்டும். 1. ஒரு கமிட் உங்கள் பயன்பாடு அல்லது நூலகத்தில் ஒரு புதிய அம்சத்தைச் சேர்க்கும்போது `feat` வகையைப் பயன்படுத்த வேண்டும். 1. ஒரு கமிட் உங்கள் பயன்பாட்டிற்கான பிழைத் தீர்வைக் குறிக்கும் போது `fix` வகையைப் பயன்படுத்த வேண்டும். 1. ஒரு வகைக்குப் பிறகு ஒரு நோக்கம் வழங்கப்படலாம். ஒரு நோக்கம், அடைப்புக்குறிகளால் சூழப்பட்ட குறியீட்டுத் தளத்தின் பகுதியை விவரிக்கும் பெயர்ச்சொல்லைக் கொண்டிருக்க வேண்டும், எ.கா., `fix(parser):` 1. ஒரு விளக்கம் உடனடியாக பெருங்குடல் மற்றும் வகை/நோக்க முன்னொட்டுக்குப் பிறகு இடைவெளியைத் தொடர்ந்து வர வேண்டும்.விளக்கம் என்பது குறியீட்டு மாற்றங்களின் சுருக்கமான சுருக்கமாகும், எ.கா., _fix: string_ இல் பல இடைவெளிகள் இருந்தபோது வரிசை பாகுபடுத்தும் சிக்கல். 1. குறுகிய விளக்கத்திற்குப் பிறகு ஒரு நீண்ட கமிட் உடல் வழங்கப்படலாம், இது குறியீடு மாற்றங்கள் பற்றிய கூடுதல் சூழல் தகவலை வழங்குகிறது. விளக்கத்திற்குப் பிறகு ஒரு புதிய வரி தொடங்க வேண்டும். 1. ஒரு கமிட் உடல் கட்டற்ற வடிவத்தைக் கொண்டுள்ளது மற்றும் புதிய வரி பிரிக்கப்பட்ட எத்தனை பத்திகளைக் கொண்டிருக்கலாம். 1. ஒன்று அல்லது அதற்கு மேற்பட்ட அடிக்குறிப்புகளுக்கு உடலுக்குப் பிறகு ஒரு வெற்று வரி வழங்கப்படலாம். ஒவ்வொரு அடிக்குறிப்பிலும் ஒரு சொல் டோக்கன் இருக்க வேண்டும், அதைத் தொடர்ந்து `:` அல்லது `#` ஒரு பிரிப்பான் இருக்க வேண்டும், அதைத் தொடர்ந்து ஒரு சரம் மதிப்பு இருக்க வேண்டும் (இது[git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 1. ஒரு அடிக்குறிப்பின் டோக்கன் இடைவெளி எழுத்துகளுக்குப் பதிலாக `-` ஐப் பயன்படுத்த வேண்டும், எ.கா., `Acked-by` (இது அடிக்குறிப்புப் பகுதியை பல-பத்தி உள்ளடக்கத்திலிருந்து வேறுபடுத்த உதவுகிறது). `BREAKING CHANGE` க்கு விதிவிலக்கு அளிக்கப்படுகிறது, இது ஒரு டோக்கனாகவும் பயன்படுத்தப்படலாம். 1. ஒரு அடிக்குறிப்பின் மதிப்பில் இடைவெளிகள் மற்றும் புதிய வரிகள் இருக்கலாம், மேலும் அடுத்த செல்லுபடியாகும் அடிக்குறிப்பு டோக்கன்/ ஒரு பிரிப்பான் ஜோடி கவனிக்கப்படும்போது பாகுபடுத்தல் முடிவடைய வேண்டும். 1. உடைக்கும் மாற்றங்கள் ஒரு கமிட்டின் வகை/ஸ்கோப் முன்னொட்டில் அல்லது அடிக்குறிப்பில் உள்ளீட்டாகக் குறிக்கப்பட வேண்டும். 1. அடிக்குறிப்பாகச் சேர்க்கப்பட்டால், உடைக்கும் மாற்றம் பெரிய எழுத்து உரையான BREAKING CHANGE ஐக் கொண்டிருக்க வேண்டும், அதைத் தொடர்ந்து ஒரு பெருங்குடல், இடைவெளி மற்றும் விளக்கம் இருக்க வேண்டும், எ.கா., _BREAKING CHANGE: சூழல் மாறிகள் இப்போது config files_ ஐ விட முன்னுரிமை பெறுகின்றன. 1. வகை/ஸ்கோப் முன்னொட்டில் சேர்க்கப்பட்டால், உடைக்கும் மாற்றங்களை `:` க்கு உடனடியாக முன் ஒரு `!` ஆல் குறிக்க வேண்டும். `!` பயன்படுத்தப்பட்டால், `BREAKING CHANGE:` அடிக்குறிப்புப் ஒரு பிரிவில் இருந்து தவிர்க்கப்படலாம்,மேலும் commit-க்கு விளக்கம் முறிவு மாற்றத்தை விவரிக்கப் பயன்படுத்தப்படும். 1. `feat` மற்றும் `fix` தவிர பிற வகைகள் உங்கள் commit செய்திகளில் பயன்படுத்தப்படலாம், எ.கா., _docs: update ref docs._ 1. வழக்கமான commitகளை உருவாக்கும் தகவலின் அலகுகளை செயல்படுத்துபவர்கள் பெரிய எழுத்தில் இருக்க வேண்டிய BREAKING CHANGE தவிர, செயல்படுத்துபவர்களால் பேரெழுத்து உணர்திறன் கொண்டதாகக் கருதக்கூடாது. 1. அடிக்குறிப்பில் டோக்கனாகப் பயன்படுத்தப்படும்போது BREAKING-CHANGE BREAKING CHANGE உடன் ஒத்ததாக இருக்க வேண்டும். ## வழக்கமான commitகளை ஏன் பயன்படுத்த வேண்டும் * தானாகவே CHANGELOGS ஐ உருவாக்குகிறது. * ஒரு சொற்பொருள் பதிப்பு பம்பை தானாக தீர்மானித்தல் (இறக்கப்பட்ட commit வகைகளின் அடிப்படையில்). * மாற்றங்களின் தன்மையை குழு உறுப்பினர்கள், பொதுமக்கள் மற்றும் பிற பங்குதாரர்களுக்குத் தெரிவித்தல். * உருவாக்க மற்றும் வெளியிடும் செயல்முறைகளைத் தூண்டுதல். * உங்கள் திட்டங்களுக்கு மக்கள் பங்களிப்பதை எளிதாக்குவதன் மூலம், அவர்களை ஆராய அனுமதிப்பது மிகவும் கட்டமைக்கப்பட்ட கமிட் வரலாறு. ## அடிக்கடி கேட்கப்படும் கேள்விகள் ### ஆரம்ப கட்டத்தில் கமிட் செய்திகளை நான் எவ்வாறு கையாள வேண்டும்? நீங்கள் ஏற்கனவே தயாரிப்பை வெளியிட்டது போல் தொடர பரிந்துரைக்கிறோம். பொதுவாக *யாராவது*, அது உங்கள் சக மென்பொருள் உருவாக்குநர்களாக இருந்தாலும் கூட, உங்கள் மென்பொருளைப் பயன்படுத்துகிறார்கள். என்ன சரி செய்யப்பட்டது, என்ன உடைகிறது போன்றவற்றை அவர்கள் அறிய விரும்புவார்கள். ### கமிட் தலைப்பில் உள்ள வகைகள் பெரிய எழுத்தா அல்லது சிறிய எழுத்தா? எந்த உறையையும் பயன்படுத்தலாம், ஆனால் சீராக இருப்பது நல்லது. ### கமிட் ஒன்றுக்கு மேற்பட்ட கமிட் வகைகளுக்கு இணங்கினால் நான் என்ன செய்வது? திரும்பிச் சென்று முடிந்தவரை பல கமிட்களைச் செய்யுங்கள். வழக்கமான கமிட்களின் நன்மையின் ஒரு பகுதி, மேலும் ஒழுங்கமைக்கப்பட்ட கமிட்கள் மற்றும் PRகளை உருவாக்க நம்மைத் தூண்டும் திறன் ஆகும். ### இது விரைவான மேம்பாடு மற்றும் வேகமான மறு செய்கையை ஊக்கப்படுத்தவில்லையா? இது ஒழுங்கற்ற முறையில் வேகமாக நகர்வதை ஊக்கப்படுத்துகிறது. இது பல்வேறு பங்களிப்பாளர்களைக் கொண்ட பல திட்டங்களில் நீண்ட காலத்திற்கு வேகமாக நகர உங்களுக்கு உதவுகிறது. ### வழக்கமான கமிட்கள், டெவலப்பர்கள் வழங்கப்படும் வகைகளில் சிந்திப்பதால், அவர்கள் செய்யும் கமிட்களின் வகையை வரம்பிட வழிவகுக்குமா? வழக்கமான கமிட்கள், திருத்தங்கள் போன்ற சில வகையான கமிட்களை அதிகமாகச் செய்ய எங்களை ஊக்குவிக்கின்றன. அதைத் தவிர, வழக்கமான கமிட்களின் நெகிழ்வுத்தன்மை உங்கள் குழு அவர்களின் சொந்த வகைகளைக் கொண்டு வந்து காலப்போக்கில் அந்த வகைகளை மாற்ற அனுமதிக்கிறது. ### இது SemVer உடன் எவ்வாறு தொடர்புடையது? `fix` வகை கமிட்கள் `PATCH`-க்கு வெளியீடுகளாக மொழிபெயர்க்கப்பட வேண்டும். `feat` வகை கமிட்கள் `MINOR`-க்கு வெளியீடுகளாக மொழிபெயர்க்கப்பட வேண்டும். கமிட்களில் `BREAKING CHANGE` உடன் உள்ள கமிட்கள், வகையைப் பொருட்படுத்தாமல், `MAJOR` -க்கு வெளியீடுகளாக மொழிபெயர்க்கப்பட வேண்டும். ### எனது நீட்டிப்புகளை வழக்கமான கமிட்ஸ்விவரக்குறிப்புக்கு எவ்வாறு பதிப்பு செய்ய வேண்டும், எ.கா. `@jameswomack/conventional-commit-spec`? இந்த விவரக்குறிப்புக்கு உங்கள் சொந்த நீட்டிப்புகளை வெளியிட SemVer ஐப் பயன்படுத்த பரிந்துரைக்கிறோம் (மேலும் இந்த நீட்டிப்புகளை உருவாக்க உங்களை ஊக்குவிக்கிறோம்!) ### நான் தற்செயலாக தவறான கமிட் வகையைப் பயன்படுத்தினால் நான் என்ன செய்வது? #### நீங்கள் ஸ்பெக்கில் இருக்கும் ஆனால் சரியான வகை அல்லாத ஒரு வகையைப் பயன்படுத்தும்போது, ​​எ.கா. `feat` க்கு பதிலாக `fix` தவறை ஒன்றிணைப்பதற்கு அல்லது வெளியிடுவதற்கு முன், கமிட் வரலாற்றைத் திருத்த `git rebase -i` ஐப் பயன்படுத்த பரிந்துரைக்கிறோம். ஒரு வெளியீட்டிற்குப் பிறகு, நீங்கள் பயன்படுத்தும் கருவிகள் மற்றும் செயல்முறைகளைப் பொறுத்து சுத்தம் செய்தல் வேறுபட்டதாக இருக்கும். #### நீங்கள் ஸ்பெக்கின் *அல்லாத* வகையைப் பயன்படுத்தும்போது, ​​எ.கா. `feat` க்கு பதிலாக `feet` மோசமான சூழ்நிலையில், ஒரு கமிட் வழக்கமான கமிட்ஸ் விவரக்குறிப்பை பூர்த்தி செய்யாவிட்டால் அது உலகின் முடிவு அல்ல. இதன் பொருள், விவரக்குறிப்பை அடிப்படையாகக் கொண்ட கருவிகளால் கமிட் தவறவிடப்படும். ### எனது பங்களிப்பாளர்கள் அனைவரும் வழக்கமான விவரக்குறிப்பைப் பயன்படுத்த வேண்டுமா? இல்லை! நீங்கள் Git-இல் ஸ்குவாஷ் அடிப்படையிலான பணிப்பாய்வைப் பயன்படுத்தினால், லீட் பராமரிப்பாளர்கள் கமிட் செய்திகளை ஒன்றிணைக்கும்போது சுத்தம் செய்யலாம் - சாதாரண கமிட்டர்களுக்கு எந்த பணிச்சுமையும் சேர்க்காது. இதற்கான பொதுவான பணிப்பாய்வு என்னவென்றால், உங்கள் ஜிட் அமைப்பு ஒரு புல் கோரிக்கையிலிருந்து தானாகவே கமிட் செய்து, இணைப்பிற்கான சரியான கிட் கமிட் செய்தியை உள்ளிட லீட் பராமரிப்பாளருக்கு ஒரு படிவத்தை வழங்குவதாகும். ### வழக்கமான கமிட்ஸ் எவ்வாறு ரிவர்ட் கமிட்களைக் கையாளுகிறது? குறியீட்டை மாற்றுவது சிக்கலானதாக இருக்கலாம்: நீங்கள் பல கமிட்களை மாற்றுகிறீர்களா? நீங்கள் ஒரு அம்சத்தை மாற்றினால், அடுத்த வெளியீடு ஒரு பேட்சாக இருக்க வேண்டுமா? வழக்கமான கமிட்ஸ் மாற்ற நடத்தையை வரையறுக்க வெளிப்படையான முயற்சியை மேற்கொள்ளவில்லை. அதற்கு பதிலாக, கருவிப்படுத்தல் ஆசிரியர்கள் _types_ மற்றும் _footers_ இன் நெகிழ்வுத்தன்மையைப் பயன்படுத்தி ரிவர்ட்களைக் கையாள்வதற்கான அவர்களின் தர்க்கத்தை உருவாக்க வேண்டும். ஒரு பரிந்துரை என்னவென்றால், `revert` வகையைப் பயன்படுத்துவதும், மாற்றியமைக்கப்படும் commit SHA-களைக் குறிப்பிடும் அடிக்குறிப்பையும் பயன்படுத்துவதும் ஆகும்: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.th.md ================================================ --- draft: false aliases: ["/th/"] --- # Conventional Commits 1.0.0 ## ข้อสรุป ข้อกำหนดของ Conventional Commits คือข้อตกลงอย่างง่ายที่สร้างขึ้นสำหรับข้อความที่ commit ข้อกำหนดนี้จะรวมข้อกำหนดในการสร้างข้อความในการ commit อย่างชัดเจน ซึ่งจะช่วยให้สามารถเขียนชุดเครื่องมืออัตโนมัติต่อยอดได้ง่ายขึ้น ข้อตกลงนี้จะใช้รูปแบบเดียวกับ [SemVer](http://semver.org) โดยมีการอธิบายถึงฟีเจอร์ การแก้ไขต่าง ๆ และการเปลี่ยนแปลงที่ขัดต่อเวอร์ชั่นก่อนหน้าลงไปในข้อความที่ commit ข้อความที่ commit ควรจะมีโครงสร้างตามนี้ --- ``` <ชนิด>[ละได้ ขอบเขต]: <รายละเอียด> [ละได้ เนื้อหา] [ละได้ ข้อความลงท้าย] ``` ---
โดย commit จะมีหน่วยโครงสร้างย่อย ๆ ตามนี้ เพื่อใช้ในการสื่อสารถึงความตั้งใจให้กับคนที่นำไลบรารี่ของคุณไปใช้งาน 1. **fix:** commit ที่มี _ชนิด_ `fix` หมายถึงมีการแก้ไขบักในโค้ดของคุณ (จะสอดคล้องกับ [`PATCH`](http://semver.org/#summary) ใน Semantic Versioning) 2. **feat:** commit ที่มี _ชนิด_ `feat` หมายถึงมีการเพิ่มฟีเจอร์ใหม่เข้าไปในโค้ด (จะสอดคล้องกับ [`MINOR`](http://semver.org/#summary) ใน Semantic Versioning) 3. **BREAKING CHANGE:** commit ที่ลงท้ายด้วย `BREAKING CHANGE:` ในข้อความลงท้าย หรือ ต่อท้ายด้วย `!` หลังจาก type หรือ scope จะหมายถึงมีการเพิ่มการเปลี่ยนแปลงที่กระทบกับ API เดิม (จะสอดคล้องกับ [`MAJOR`](http://semver.org/#summary) ใน Semantic Versioning) โดยที่ BREAKING CHANGE สามารถเป็นส่วนหนึ่งของ commit _ชนิด_ ไหนก็ได้ 1. _ชนิด_ อื่น ๆ ที่ไม่ใช่ `fix:` and `feat:` สามารถใช้ได้เช่นกัน เช่น [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (อ้างอิงจาก [ข้อตกลงของ Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) ได้แนะนำชนิด `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` และอื่น ๆ 1. _ข้อความลงท้าย_ ที่นอกเหนือจาก `BREAKING CHANGE: <รายละเอียด>` สามารถใช้ได้ และเขียนตามข้อตกลงเดียวกันกับ [git trailer format](https://git-scm.com/docs/git-interpret-trailers) ชนิดอื่น ๆ เพิ่มเติมไม่ได้อยู่ในขอบเขตตามข้อกำหนดของ Conventional Commits นี้ และไม่ได้มีผลกระทบอะไรใน Semantic Versioning (ถ้าไม่ได้ระบุใน BREAKING CHANGE)

ขอบเขตอาจจะถูกระบุไปกับชนิดของ commit เพื่อบอกข้อมูลของบริบทเพิ่มเติม โดยจะระบุอยู่ในเครื่องหมายวงเล็บ เช่น `feat(parser): add ability to parse arrays` ## ตัวอย่าง ### ข้อความ commit ที่มีการระบุรายละเอียด และลงท้ายด้วย breaking change ในข้อความลงท้าย ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### ข้อความ commit ที่มี `!` เพื่อบ่งบอก breaking change ``` feat!: send an email to the customer when a product is shipped ``` ### ข้อความ commit ที่ระบุขอบเขต และมี `!` เพื่อบ่งบอก breaking change ``` feat(api)!: send an email to the customer when a product is shipped ``` ### ข้อความ commit ที่มีทั้ง `!` และ BREAKING CHANGE ลงท้าย ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### ข้อความ commit ที่ไม่มีเนื้อหา ``` docs: correct spelling of CHANGELOG ``` ### ข้อความ commit ที่ระบุขอบเขต ``` feat(lang): add polish language ``` ### ข้อความ commit ที่มีเนื้อหาหลายย่อหน้า และมีข้อความลงท้ายหลายข้อความ ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## ข้อกำหนด คำสำคัญ “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, และ “OPTIONAL” ในเอกสารฉบับนี้จะถูกแปลตามที่อธิบายไว้ใน [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 1. ข้อความ commit จะต้องขึ้นต้นด้วย ชนิด ซึ่งประกอบด้วยคำนาม `feat`, `fix`, ฯลฯ และตามด้วยขอบเขตซึ่งอาจจะละไว้ได้ และตามด้วย `!` ซึ่งอาจจะละไว้ได้ และเครื่องหมายโคล่อน (:) และเว้นวรรค 2. ชนิด `feat` จะถูกใช้เมื่อใน commit นั้นมีการเพิ่มฟีเจอร์ใหม่เข้าไปในแอพพลิเคชั่น หรือไลบรารี่ของคุณ 3. ชนิด `fix` จะถูกใช้เมื่อ commit นั้นเป็นการแก้ไขบักสำหรับแอพพลิเคชั่นของคุณ 4. ขอบเขตอาจจะถูกเขียนหลังจากชนิด โดยขอบเขตจะต้องอธิบายได้ถูกส่วนของโค้ด และอยู่ภายใต้วงเล็บ เช่น `fix(parser):` 5. คำอธิบายจะต้องอยู่ต่อจากเครื่องหมายโคล่อนและเว้นวรรคที่อยู่หลังจากชนิดและขอบเขตในตอนแรกทันที คำอธิบายจะเป็นข้อความสรุปอย่างสั้นสำหรับการเปลี่ยนแปลงของโค้ด เช่น _fix: array parsing issue when multiple spaces were contained in string_ 1. เนื้อหา commit ที่ยาวกว่าสามารถใส่เพิ่มหลังจากข้อความ commit แบบสั้นแล้วได้ โดยให้ใส่ข้อมูลในบริบทเพิ่มเติมที่เกี่ยวข้องกับความเปลี่ยนแปลงของโค้ด โดยเนื้อหานี้จะต้องเริ่มด้วยการเว้นบรรทัดว่างหนึ่งบรรทัดหลังจากรายละเอียดของ commit ในบรรทัดแรก 2. เนื้อหา commit ใส่ได้ตามอิสระ และอาจจะมีหลายย่อหน้าก็ได้ 3. ข้อความลงท้ายอาจจะมีมากกว่าหนึ่ง และจะต้องอยู่หลังจากเนื้อหาโดยการเว้นบรรทัดว่างหนึ่งบรรทัด โดยข้อความลงท้ายแต่ละข้อความจะต้องประกอบด้วย กลุ่มคำ และตามด้วย `:<เว้นวรรค>` หรือ `<เว้นวรรค>#` เป็นตัวคั่น และตามด้วยข้อความ (ส่วนนี้ได้แรงบันดาลใจมาจาก [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)) 4. กลุ่มคำในข้อความลงท้ายจะต้องใช้ `-` แทนช่องว่าง เช่น `Acked-by` (ซึ่งจะช่วยแยกแยะส่วนที่เป็นข้อความลงท้ายกับเนื้อหาที่มีหลายย่อหน้าออกจากกัน) ข้อยกเว้นเดียวคือ `BREAKING CHANGE` ซึ่งอาจจะถูกใช้เป็นกลุ่มคำได้เช่นกัน 5. ข้อความในข้อความลงท้ายอาจจะมีเว้นวรรค และมีการขึ้นบรรทัดใหม่ก็ได้ การแยกข้อความลงท้ายหนึ่งข้อความจะสิ้นสุดเมื่อเจอกลุ่มคำและตัวคั่นในข้อความลงท้ายถัดไป 6. การเปลี่ยนแปลงที่มีผลกระทบจะต้องมีการบ่งชี้ให้เห็นในส่วนของชนิด หรือขอบเขตในตอนต้น หรือเป็นส่วนหนึ่งของข้อความลงท้าย 7. ถ้าการเปลี่ยนแปลงที่มีผลกระทบเป็นส่วนหนึ่งของข้อความลงท้าย การเปลี่ยนแปลงนั้นจะต้องขึ้นต้นด้วยคำว่า BREAKING CHANGE (ตัวอักษรตัวใหญ่ทั้งหมด) และตามด้วยเครื่องหมายโคลอน `:` เว้นวรรค และรายละเอียด เช่น _BREAKING CHANGE: environment variables now take precedence over config files_ 1. ถ้าการเปลี่ยนแปลงที่มีผลกระทบเป็นส่วนหนึ่งของชนิดหรือขอบเขตในตอนต้น จะต้องใส่ `!` ต่อท้ายทันที ก่อนเครื่องหมายโคลอน `:` และเมื่อใช้ `!` อาจจะไม่ต้องใส่ `BREAKING CHANGE:` ในข้อความลงท้ายก็ได้ และรายละเอียดของ commit จะถูกใช้เพื่ออธิบายถึงสิ่งที่กระทบนั้น ๆ 2. ชนิดของ commit อื่น ๆ นอกเหนือจาก `feat` และ `fix` อาจจะถูกใช้ในข้อความ commit ได้ เช่น _docs: updated ref docs._ 3. ส่วนประกอบอื่น ๆ ใน Conventional Commits จะไม่ไม่ให้ความสำคัญกับตัวอักษรใหญ่หรือเล็ก ยกเว้นแต่คำว่า BREAKING CHANGE ซึ่งจะต้องเป็นตัวใหญ่เสมอ 4. BREAKING-CHANGE จะมีความหมายเดียวกันกับ BREAKING CHANGE เมื่อถูกใช้เป็นกลุ่มคำในข้อความลงท้าย ## ทำไมถึงควรใช้ Conventional Commits * ใช้ในการสร้าง CHANGELOG โดยอัตโนมัติ * ใช้ช่วยในการตัดสินใจในการปรับเวอร์ชั่นตาม semantic version โดยอัตโนมัติ (โดยดูจากชนิดของ commit ที่บันทึก) * ใช้สื่อสารถึงธรรมชาติของการเปลี่ยนแปลงให้กับเพื่อนร่วมทีม สาธารณะ และผู้ที่เกี่ยวข้องอื่น ๆ * ใช้เริ่มกระบวนการ build และการเผยแพร่สู่สาธารณะ * ช่วยให้ผู้ที่จะมีส่วนร่วมในโปรเจกต์ทำงานได้ง่ายขึ้นโดยช่วยให้พวกเขาสามารถดูข้อความ commit ย้อนหลังแบบมีโครงสร้างได้ ## คำถามที่พบบ่อย ### ฉันจะจัดการกับข้อความ commit ในช่วงเริ่มต้นของการพัฒนาได้อย่างไร? เราแนะนำให้คุณทำเหมือนกับคุณได้รีลีสผลิตภัณฑ์ของคุณแล้ว โดยปกติ *บางคน* ถึงแม้จะหมายถึงเพื่อนร่วมทีมพัฒนาซอฟต์แวร์ของคุณก็ตาม มาใช้ซอฟต์แวร์ของคุณ เขาก็อยากที่จะรู้ว่าส่วนไหนถูกแก้ไขแล้ว ส่วนไหนที่มีการเปลี่ยนแปลง และรายละเอียดส่วนอื่น ๆ ### ชนิดของ commit ควรจะเป็นตัวใหญ่ หรือตัวเล็ก? จะเป็นตัวใหญ่หรือตัวเล็กก็ได้ แต่มันจะเยี่ยมมากถ้ามันสอดคล้องกันทั้งหมด ### ฉันควรจะทำอย่างไรถ้า commit นั้นเป็นไปได้มากกว่าหนึ่งชนิด​? กลับไปแก้ไขและพยายามแบ่งออกให้เป็นหลาย commit เท่าที่จะเป็นไปได้ ประโยชน์ส่วนหนึ่งของ Conventional Commits คือการที่มันช่วยให้เราสามารถจัดการกับ commit และ PR ได้ดีกว่าเดิม ### นี่มันจะไม่ทำให้การพัฒนาและรอบการทำงานช้าลงกว่าเดิมหรือ? มันทำให้การทำงานแบบไม่มีการจัดการช้าลง แต่มันจะช่วยให้คุณทำงานได้เร็วขึ้นในระยะยาวกับหลาย ๆ โปรเจกต์ที่มีส่วนร่วมจากหลาย ๆ คน ### Conventional Commits จะทำให้นักพัฒนาจำกัดจำนวนของชนิดที่พวกเขาทำเพราะจะทำให้พวกเขาติดอยู่กับชนิดที่มีอยู่หรือไม่? Conventional Commits สนับสนุนเราให้สามารถสร้างชนิดได้มากกว่านั้น เช่น fixes นอกจากนั้นแล้ว ความยืดหยุ่นของ Conventional Commits ยังอนุญาตให้ทีมของคุณสร้างชนิดของพวกเขาขึ้นมาเอง และปรับเปลี่ยนมันได้ตลอดเวลาอีกด้วย ### นี่เกี่ยวข้องกับ SemVer อย่างไร? commit ที่มีชนิดเป็น `fix` จะถูกมองเป็น `PATCH` ใน release ส่วน commit ชนิดที่เป็น `feat` จะถูกมองเป็น `MINOR` release และ commits ที่เป็น `BREAKING CHANGE` ไม่ว่าจะเป็นชนิดใดก็ตาม จะถูกมองเป็น `MAJOR` release ### ฉันควรจะใส่เวอร์ชั่นของส่วนขยายให้กับข้อกำหนดของ Conventional Commits อย่างไร เช่น `@jameswomack/conventional-commit-spec`? เราแนะนำให้ใช้ SemVer ในการที่จะรีลีสส่วนขยายของคุณให้กับข้อกำหนดนี้ (และสนับสนุนให้คุณสร้างส่วนขยายนี้ด้วย!) ### ฉันจะทำอย่างไรถ้าฉันใส่ชนิดของ commit ผิดโดยไม่ได้ตั้งใจ? #### เมื่อคุณใช้ชนิดที่เป็นส่วนหนึ่งในข้อตกลง แต่ผิดชนิด เช่น ใช้ `fix` แทนที่จะเป็น `feat` ก่อนที่จะรวม หรือรีลีสความผิดพลาดนั้น เราแนะนำให้ใช้ `git rebase -i` เพื่อแก้ไขข้อความใน commit ย้อนหลัง แต่ถ้าทำหลังจากที่รีลีสไปแล้ว การแก้ไขจะแตกต่างกันไปขึ้นอยู่กับเครื่องมือและวิธีการที่คุณใช้ #### เมื่อคุณใช้ชนิดที่ *ไม่ได้* เป็นส่วนหนึ่งในข้อตกลง เช่น ใช้ `feet` แทนที่จะเป็น `feat` ในสถานการณ์ที่แย่ที่สุด มันไม่ใช่วันสิ้นโลกถ้าคุณจะใส่ commit ที่ไม่สอดคล้องกับข้อกำหนดของ Conventional Commits มันมีความหมายง่าย ๆ คือ commit นั้นจะถูกมองข้ามไปถ้าใช้เครื่องมือที่อ้างอิงตามข้อกำหนดนี้เท่านั้นเอง ### คนที่มีส่วนร่วมในโปรเจกต์ทั้งหมดจะต้องใช้ข้อกำหนดของ Conventional Commits นี้หรือไม่? ไม่! ถ้าคุณใช้ลำดับการทำงานแบบที่ต้องยุบรวม commit บน Git คนที่เป็นผู้ดูแลจะสามารถจัดการกับข้อความ commit ในขณะที่รวม commit เข้ามาโดยที่ไม่เป็นภาระกับผู้ที่ไม่ค่อยได้ commit ลำดับการทำงานโดยทั่วไปสำหรับแบบนี้คือต้องทำให้ระบบ git ของคุณทำการยุบรวม commit ที่มาจาก pull request โดยอัตโนมัติ และแนะนำฟอร์มให้กับผู้ดูแลเพื่อใส่ข้อความ commit ที่เหมาะสมในการรวม commit เข้ามา ### Conventional Commits จะจัดการกับการย้อนกลับ commit ได้อย่างไร? การย้อนกลับโค้ดอาจจะซับซ้อนได้: คุณกำลังย้อนกลับหลาย ๆ commit หรือไม่? ถ้าคุณกำลังย้อนกลับฟีเจอร์ ในการรีลีสซอฟต์แวร์ครั้งถัดไปจะกลายเป็นเพียงการ patch หรือไม่? Conventional Commits ไม่ได้บอกถึงวิธีการอย่างชัดเจนว่าจะต้องทำอย่างไรเมื่อเกิดการย้อนกลับ แต่เราปล่อยให้เป็นการจัดการของนักพัฒนาเครื่องมือเป็นผู้ใช้ความยืดหยุ่นของ _ชนิด_ และ _ข้อความลงท้าย_ ในการพัฒนาตรรกะในการจัดการการย้อนกลับ คำแนะนำหนึ่งคือการใช้ชนิด `revert` และข้อความลงท้ายที่มีการอ้างถึงหมายเลข commit ที่จะถูกย้อนกลับ ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.tr.md ================================================ --- draft: false aliases: ["/tr/"] --- # Conventional Commits 1.0.0 ## Özet Conventional Commits yönergesi, commit mesajları hakkında kolayca takip edilebilecek bir sözleşmedir. Anlaşılabilir bir commit geçmişi için kolay bir dizi kurallar oluşturarak, üzerine daha kolay otomatik araçlar yazılmasını sağlar. Bu sözleşme, commit mesajlarında yeni özellik ekleme (features), hata düzeltme (fixes) ve köklü değişiklik (breaking changes) tanımlamalarıyla [SemVer](http://semver.org) ile uyumludur. Commit mesajı aşağıdaki gibi yapılandırılmalıdır: --- ``` [isteğe bağlı kapsam alanı]: [isteğe bağlı mesaj metni] [isteğe bağlı alt metin(ler)] ``` ---
Commit mesajı kütüphanenizin kullanıcılarına niyet belirtmek için aşağıdaki yapısal unsurları içerir: 1. **fix:** `fix` *tipi* bir commit, kodunuzdaki bir hatayı düzeltir (Semantik versiyonlamadaki [`PATCH`](http://semver.org/#summary) ile paraleldir). 2. **feat:** `feat` *tipi* bir commit, kodunuza yeni bir özellik ekler (Semantik versiyonlamadaki [`MINOR`](http://semver.org/#summary) ile paraleldir). 3. **BREAKING CHANGE:** `BREAKING CHANGE:` ile başlayan bir alt metin ya da tip/kapsam sonuna eklenmiş bir `!` içeren commit köklü bir değişiklik getiriyordur (Semantik versiyonlamadaki [`MAJOR`](http://semver.org/#summary) ile paraleldir). Bir BREAKING CHANGE herhangi bir *tip* commit içinde olabilir. 4. `fix:` ve `feat:` dışındaki *tipler* de kullanılabilir. Örneğin [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) ([Angular yönergesine göre](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, ve birkaç başka tipi de tavsiye eder. 5. `BREAKING CHANGE: ` dışında *alt metinler* de kullanılabilir ve [git trailer format](https://git-scm.com/docs/git-interpret-trailers)'a benzer yönergeler takip edilebilir. Harici ek tipler Conventional Commits yönergesi tarafından zorunlu kılınmaz ve semantik versiyon oluşturmada tam bir etkisi yoktur (tabiki BREAKING CHANGE içermedikçe).

Fazladan ilave bağlamsal bilgi sağlamak için bir commit türüne bir kapsam eklenebilir ve parantez içinde yer alır, Örneğin, `feat(parser): add ability to parse arrays`. ## Örnekler ### Açıklama ve köklü değişiklik içeren alt metinli bir commit mesajı ``` feat: config nesnelerinin birbirinden türetilmesi sağlandı BREAKING CHANGE: `extends` kelimesi artık başka bir ayar dosyasından türetildiğini belirtiyor ``` ### Köklü değişikliğe `!` ile dikkat çeken commit mesajı ``` feat!: müşteriye, ürünü kargolandığında mail atma özelliği eklendi ``` ### Kapsam içeren ve köklü değişikliğe `!` ile dikkat çeken commit mesajı ``` feat(api)!: müşteriye, ürünü kargolandığında mail atma özelliği eklendi ``` ### `!` ve köklü değişiklik alt metni içeren commit mesajı ``` feat:! Node 6 desteği kaldırıldı BREAKING CHANGE: Sadece Node 6 içinde olan Javascript özellikleri kullanan yerler yeniden yazılmalı. ``` ### Mesaj metni olamayan commit mesajı ``` docs: CHANGELOG'daki yazım hataları düzeltildi ``` ### Kapsam içeren commit mesajı ``` feat(lang): Türkçe çeviri eklendi ``` ### Çok paragraflı mesaj metni ve birden çok alt metin içeren commit mesajı ``` fix: bazı küçük yazım hataları düzeltildi Detaylar için ilgili issue'ya bakabilirsiniz. Daha detaylı bakılması da gerekebilir. Reviewed-by: Z Refs #133 ``` ## Yönerge Bu belgedeki “-MALI”, “-MAMALI”, “ZORUNLU”, “YAPALIM”, “YAPMAYALIM”, “-SAM IYI OLUR”, “-MASAM IYI OLUR”, “TAVSIYE EDILIR”, “-ABİLİRİM” ve “SEÇMELİ” kalıpları [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)'da açıklandığı gibi yorumlanmalıdır. 1. Her commit mesajı bir `feat`, `fix`, vs. gibi bir tip ile başlaMALI, SEÇMELİ bir kapsam, SEÇMELİ bir `!` işareti ve ZORUNLU bir iki nokta üst üste işareti ve bir adet boşluk ile devam eder. 2. `feat` tipi commit, uygulamaya ya da kütüphaneye yeni bir özellik ekliyorsa kullanılMALI. 3. `fix` tipi commit, uygulamadaki bir hatayı düzeltiyorsa kullanılMALI. 4. Tip bilgisinden sonra bir kapsam belirtilEBİLİR. Kapsam bilgisi parantez içerisinde kodun hangi bölümünün değiştiğini açıklayan bir isimden oluşMALI. Örneğin `fix(parser):`. 5. Açıklama ön tip/kapsam bilgilerinden sonraki iki nokta ve boşluktan hemen sonra yazılMALIdır. Açıklama kısmı yapılan değişikliği anlatan kısa bir özettir. Örneğin *fix: array parsing issue when multiple spaces were contained in string*. 6. Kısa açıklamadan sonra, kod değişiklikleri hakkında ek bağlamsal bilgiler sağlayan daha uzun bir commit mesajı metni yazılABİLİR. Mesaj metni açıklamadan sonra boş bir satırdan sonra başlaMALIDIR. 7. Bir commitin mesaj metni serbest şekildedir ve boş bir satırla ayrılan herhangi bir sayıda paragraftan oluşABİLİR. 8. Bir ya da birden fazla alt metin mesaj metninden bir boş satır sonra koyulABİLİR. Her alt metin bir anahtar kelime ile başlaMALI, anahtar kelime ya `:` ile ya da `#` ayraçları ile bir metine bağlanmalı (bu özellik [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)'dan ilham alınmıştır). 9. Alt metin anahtar kelimesi boşluk karakteri yerine `-` kullanmalı. Örneğin `Acked-by` (bu alt metnin çok paragraflı mesaj metinlerinden ayırılmasına yardımcı olur). Buna istisna olarak sadece `BREAKING CHANGE` kalıbının anahtar kelime olarak kullanımına izin verilmiştir. 10. Alt metin birden fazla boşluk ve satır içerEBİLİR, ve bir sonraki geçerli anahtar kelimeye ulaştığında bitmiş olMALI. 11. Köklü değişiklikler ya tip/kapsam içinde ya da alt metin olarak belirtilMELİDİR. 12. Eğer alt metin içinde belirtiliyorsa, köklü değişiklik büyük harflerle BREAKING CHANGE ile başlaMALI, iki nokta işareti, boşluk ve açıklama ile devam etMELİDİR. Örneğin *BREAKING CHANGE: environment variables now take precedence over config files* gibi. 13. Eğer tip/kapsam içinde belirtiliyorsa, köklü değişiklikler `:` işaretinden önce `!` ile belirtilmelidir. Eğer `!` kullanılırsa alt metinde `BREAKING CHANGE:` kullanılMAYABİLİR ve commit açıklaması köklü değişikliği tanımlamak için kullanılABİLİR. 14. `feat` ve `fix` dışındaki tipler mesaj metninde tekrar kullanılABİLİR. Örneğin *docs: updated ref docs.*. 15. Conventional Commits ile harmanlanmış kalıplar, geliştiriciler tarafından büyük/küçük harf duyarlı olarak düşünülMEMELİ. Buna tek istisna BREAKING CHANGE kalıbıdır çünkü her zaman büyük harfle yazılMALIdır. 16. Alt metinde anahtar olarak kullanılırken BREAKING CHANGE BREAKING-CHANGE şeklinde yazılMALI. ## Neden Conventional Commits'e Uymalıyız - CHANGELOG'ları otomatik olarak oluşturma. - Bir semantik versiyon geçişini otomatik olarak belirleme (commit işlemlerinin tiplerine göre). - Değişikliklerin doğasını ekip arkadaşlarına, kamuya ve diğer paydaşlara iletmek. - Derleme ve yayınlama işlemlerini tetikleme. - İnsanların daha yapılandırılmış bir commit geçmişini kendi kendilerine keşfetmelerine imkan vererek projelerinize katkıda bulunmalarını kolaylaştırmak. ## SSS ### İlk geliştirme aşamasında commit mesajları ile nasıl başa çıkmalıyım? Ürünü daha önce yayınlamış gibi devam etmenizi öneririz. Tipik olarak *birisi*, diğer yazılım geliştiricileriniz olsa bile, yazılımınızı kullanıyor demektir. Neyin düzeltildiğini, neyin bozulduğunu vb. bilmek isteyeceklerdir. ### Commit başlığındaki tip bilgisi büyük harf mi veya küçük harf mi yazılmalı? Herhangi biri kullanılabilir, ancak tutarlı olmak en iyisidir. ### Yapacağım commit, commit tiplerinin birden fazlasına uygunsa ne yapmalıyım? Geri dönün ve mümkün olduğunca çok commit yapın. Conventional Commits'in avantajlarından biri, bizi daha organize commit ve PR yapmaya teşvik etmesidir. ### Bu, hızlı geliştirme ve hızlı ilerleme cesaretini kırmıyor mu? Bu, dağınıklık içinde hızlı bir şekilde hareket etmeyi önler. Uzun vadede, çeşitli katkıda bulunanlar ile birden fazla projede daha hızlı bir şekilde ilerlemenize yardımcı olur. ### Conventional Commits, sağlanan tipleri düşünecekleri için geliştiricilerin yaptıkları commit'lerin tipini sınırlamaya yönlendirebilir mi? Conventional Commits, hata düzeltmeleri(fixes) gibi kesin olan commit tiplerinden daha fazla yapmamızı teşvik eder. Bunun dışında, Conventional Commits'in esnekliği, ekibinizin kendi tiplerini bulmasına ve zamanla bu tipleri değiştirmesine olanak tanır. ### Bunun SemVer ile ilişkisi nedir? `fix` tipi commit `PATCH` sürüm olarak tercüme edilebilir. `feat` tipinde commit `MINOR` sürüm olarak tercüme edilebilir. `BREAKING CHANGE` içeren commit, tipi ne olursa olsun `MAJOR` olarak tercüme edilebilir. ### Conventional Commits yönergesinde yaptığım eklentiyi nasıl sürümlendirmeliyim, Örneğin `@jameswomack/conventional-commit-spec` şeklinde mi? Bu yönergeye ait kendi uzantılarınızı yayınlamak için SemVer kullanmanızı öneririz (ayrıca bu uzantıları oluşturmanızı destekliyoruz!). ### Yanlışlıkla yanlış bir commit tipi kullanırsam ne yapmalıyım? #### Yönergede olan ancak doğru olmayan bir tip kullandığınızda, örneğin `feat` yerine `fix` Hatayı birleştirmeden veya yayınlamadan önce, commit geçmişini düzenlemek için `git rebase -i` kullanmanızı öneririz. Yayınlandıktan sonra temizleme ise, kullandığınız araç ve işlemlere göre farklı olacaktır. #### Yönergede *olmayan* bir tür kullandığınızda, örneğin `feat` yerine `feet` En kötü durumda bile, Conventional Commits yönergesine uymayan bir commit tipi dünyanın sonu değildir. Bu sadece commit'in yönergeye dayalı araçlar tarafından, commit'in kaçırılacağı anlamına gelir. ### Tüm projeye katkıda bulunanlar Conventional Commits yönergesini kullanması gerekiyor mu? Hayır! Git'te squash tabanlı bir iş akışı kullanırsanız, proje yürütücüleri birleştirme sırasında commit mesajlarını temizleyebilir; bu da dışardan katkı yapanlara iş yükü eklemez. Bunun için yaygın bir iş akışı olarak, git sisteminizin otomatik olarak bir PR isteğinden commit mesajlarını ayırmasını ve isteği kabul edecek kişinin birleştirme sırasında uygun git commit mesajını girmesi için bir form sunmasını sağlamaktır. ### Conventional Commits geri döndürülen commit'leri nasıl ele alır? Eklenen bir kodu geri almak karmaşık olabilir: birden fazla commit'i mi geri alıyorsunuz? Bir özelliği geri alıyorsanız, bir sonraki sürüm veya belkide bir yama mı olmalı? Conventional Commits, geri döndürme davranışını tanımlamak için açık bir çaba göstermez. Bunun yerine bu işi geliştiricilere bırakıyoruz, geliştiriciler geri dönüşleri ele almak için kendi yollarını geliştirmek üzere *tiplerin* ve *alt metinlerin* esnekliğini kullanabilirler. Bir öneri şöyle olabilir, `revert` tipini ve geri döndürülen commit'in SHA bilgisini başvuran bir alt metinde belirtmektir: ``` revert: bir daha asla noodle olayından bahsetmeyelim Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.uk.md ================================================ --- draft: false aliases: ["/uk/"] --- # Політика Комітів 1.0.0 ## Вступ Політика Комітів - це полегшена угода понад стандартними повідомленнями про коміти. Вона надає легкий набір правил для створення зручної історії комітів; що робить простішим процес написання автоматичних утиліт для цього. Дана угода узгоджується з [Семантичними Версіями](https://semver.org/lang/uk/) шляхом вказування можливостей, латок, та великих змін, зроблених в коміт повідомленнях Повідомлення коміту має бути структуровано наступним чином: --- ``` <тип>[додатково]: <опис> [необов'язково тіло] [необов'язково додаток(тки)] ``` ---
Коміт містить наступні елементи структури, для повідомлення інтенції для споживачів вашої бібліотеки: 1. **fix:** коміт _типу_ `fix` виправляє ваду в вашому коді (це корелюється з [`PATCH`](https://semver.org/lang/uk/) в Семантичних Версіях). 2. **feat:** коміт _типу_ `feat` додає новий функціонал до коду (це корелюється з [`MINOR`](https://semver.org/lang/uk/) в Семантичних Версіях). 3. **BREAKING CHANGE:** коміт, що має додаток `BREAKING CHANGE:`, або суфікс `!` після типу, додає зміну в API (це корелюється з [`MAJOR`](https://semver.org/lang/uk/) в Семантичних Версіях). BREAKING CHANGE може бути частиною будь-якого _type_. 4. _types_ інші ніж `fix:` та `feat:` дозволені, для прикладу [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (базовано на [Angular домовленостях](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рекомендовані `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, та інші. 5. _footers_ інші ніж `BREAKING CHANGE: <опис>` можуть бути теж і наслідувати угоду схожу до [git trailer format](https://git-scm.com/docs/git-interpret-trailers). Додаткові типи не заборонені угодою про Політику Комітів, і не накладають додаткові умови в Семантичних Версія (окрім випадків коли вони містять BREAKING CHANGE).

Область(сфера) може бути доданою до типу коміту в дужках, для надання додаткової контекстної інформації, наприклад `feat(parser): add ability to parse arrays`. ## Приклади ### Коміт повідомлення з описом і BREAKING CHANGE додатком ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Коміт повідомлення з `!` для додаткового наголосу щодо BREAKING CHANGE ``` feat!: send an email to the customer when a product is shipped ``` ### Коміт повідомлення з контекстом та `!` аби привернути увагу до BREAKING CHANGE ``` feat(api)!: send an email to the customer when a product is shipped ``` ### Коміт повідомлення з `!` та BREAKING CHANGE додатком ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### Коміт повідомлення без тіла ``` docs: correct spelling of CHANGELOG ``` ### Коміт повідомлення з областю(сферою) ``` feat(lang): add polish language ``` ### Коміт повідомлення з тілом з кількома абзацами і додатками ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Специфікація Ключові слова “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, та “OPTIONAL” в цьому документі потрібно інтерпретувати як описано в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Коміти MUST(повинні) бути з префіксом типу, що складається з іменника `feat`, `fix`, тощо., наступним йде OPTIONAL(необов'язково) область(сфера), OPTIONAL(необов'язково) `!`, та REQUIRED(обов'язково) завершити двокрапкою та пропуском. 2. Тип `feat` MUST(повинен) використовуватися, коли коміт додає новий функціонал в ваш додаток або бібліотеку. 3. Тип `fix` MUST(повинен) використовуватися якщо коміт є латкою для вашого додатку. 4. Область(сфера) MAY(може) бути вказана після типу. Область(сфера) MUST(повинна) містити іменник, що описує секцію коду виділену лапками, наприклад, `fix(parser):` 5. Опис MUST(повинен) одразу завершатися двокрапкою і пропуском після області(сфери). Опис - це короткий підсумок змін в коді, наприклад, _fix: array parsing issue when multiple spaces were contained in string_. 6. Довге тіло коміту MAY(може) бути додано після короткого опису, надаючи додаткову контекстну інформацію про зміни в коді. Тіло MUST(повинне) починатися з однієї пустої строки після опису. 7. Тіло коміту - це вільна форма і може містити будь-яку кількість нових рядків і абзаців. 8. Один або два додатки MAY(можуть) бути надані після одного пустого рядка після тіла. Кожен додаток MUST(повинен) містити слово токен, після якого має бути або `:` або `#` роздільник, після якого має йти строкове значення (запозичено з [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)). 9. Токен додатка MUST(повинен) використовувати `-` на місці пропусків, наприкла, `Acked-by` ( це допомагає відрізнити додаток від тіла з багатьма параграфами. Виключення зроблене для `BREAKING CHANGE`, що MAY(може) також використовуватися як токен. 10. Значення додатку MAY(може) містити пропуски та нові рядки, і зчитування MUST(повинне) припинятися коли наступний коректний токен/роздільник додатку знайдено. 11. BREAKING CHANGE MUST(повинні) бути виділені в типі/області префіксі коміту, або як вміст додатку. 12. Якщо виділено в додатку, BREAKING CHANGE MUST(повинно) містити великими літерами BREAKING CHANGE, потім двокрапка, пропуск, та опис, наприклад, _BREAKING CHANGE: environment variables now take precedence over config files_. 14. Якщо вставлене в типі/області префіксом, BREAKING CHANGE MUST(повинно) бути виділено `!` одразу перед `:`. Якщо `!` використане, `BREAKING CHANGE:` MAY(може) бути упущене в додатку, і опис коміту SHALL(має) бути використаний для опису BREAKING CHANGE. 15. Типи, інші за `feat` та `fix` MAY(можуть) бути використані в ваших коміт повідомленнях, наприклад, _docs: updated ref docs._ 16. Одиниці інформації, що роблять Політику Комітів MUST NOT(не повинні) бути сприйняті як чутливими до регістру творцями інструментів, за виключенням BREAKING CHANGE, що MUST(мусить) бути великими літерами. 17. BREAKING-CHANGE MUST(повинно) бути синонімом до BREAKING CHANGE, коли використовується в додатку. ## Для чого використовувати Політику Комітів. * Автоматичне створення Нотаток про Реліз(Changelog) * Автоматичне визначення наступної версії в Семантичних Версіях(базуючись на типах комітів, що увійшли). * Комунікування природи змін для команди, в публічному просторі, до власників. * Запуск процесів компіляції та публікації. * Полегшує людям шлях до контрибуції в ваш проєкт, надаючи їм більш структуровану історію комітів. ## ЧЗП ### Як потрібно поводити себе на початковій фазі розробки? Рекомендуємо продовжувати так, наче ви вже створили реліз продукту. Типово *хтось*, навіть, якщо це ваші розробники, вже використовують ваше програмне забезпечення. Вони будуть знати, що виправлено, що поламано тощо. ### Як поводити себе з великими і малими літерами? Будь-які можуть використовуватися, вле варто притримуватися якогось одного підходу. ### Що робити, якщо коміт підходить для кількох типів одночасно? Зробіть декілька комітів, наскільки це можливо. Частина вигоди від Політики Комітів є можливість спонукати нас робити більш організовані коміти і PR/MRs ### Чи погіршує це швидку розробку і швидкі операції? Погіршення відбувається в результаті неорганізованості. Дана Політика дає можливість рухатися швидше в довготривалій перспективі з різними контрибуторами. ### Чи може Політика Комітів спонукати розробників обмежуватися окремими типами комітів через відношення до цих типів? Політика Комітів мотивує нас робити більше комітів по типу *виправлення*. Але Політика Комітів дає гнучкість з якою команда може створювати власні типи собі в зручність. ### Як це корелюється з Семантичними Версіями? Тип `fix` має бути як `PATCH` релізами. Тип `feat` має бути як `MINOR` релізи. Коміти з `BREAKING CHANGE`, незалежно від типу мають йти в `MAJOR` релізи. #### Коли використано тип із специфікації, але `fix` замість `feat`, як діяти? Перед тим, як мержити і релізити помилку, ми рекомендуємо використовувати `git rebase -i` для редагування історії комітів. Після релізу однак, виправлення буде залежати від утиліт і процесів, які ви використовуєте в себе. #### Якщо використано помилково тип не з специфікації, наприклад `feet` замість `feat` В найгіршому випадку, це не є кінцем світу і коміт просто не буде враховано утилітами, бо вони про це нічого не знають. ### Чи всі мої контрибутори мають використовувати Політику Комітів згідно спеціфікації? Ні! Якщо ви використовуєте політику об'єднання комітів, тоді в дане повідомлення лід може вписувати коміт згідно Політики Комітів, збагачуючи таким чином історію. ### Як Політика Комітів діє в якості повернення комітів(revert)? Відновлення коду може бути насправді складним, особливо, якщо відновлюється багато комітів. Якщо повертається функціонал, наступний реліз має бути латкою чи релізом? Політика Комітів ніяк не визначає поведінку щодо повернень коду. Ми залишаємо це на розсуд авторів відповідних утиліт для стратегії логіки, для чого можна використовувати типи та додатки. Наша рекомендація - використовувати тип `revert`, і додаток, що зсилається на SHA комітів, які повертаються: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.uz.md ================================================ --- draft: false aliases: ["/uz/"] --- # Conventional Commits 1.0.0 ## Xulosa Conventional Commits spetsifikatsiyasi - bu commit xabarlarni qanday yozish kerakligi haqidagi oddiy kelishuv. U tushunarli commitlar tarixini yaratish uchun oddiy qoidalar to'plamini taqdim etadi, shuningdek, commitlar tarixiga asoslangan avtomatlashtirish vositalarini ishlab chiqishni osonlashtiradi. Ushbu konventsiya [SemVer](http://semver.org) bilan bog'liq bo'lib, commit xabarlarida kiritilgan yangi xususiyatlar, tuzatishlar va o'zgarishlarni ifodalaydi. Commit xabari quyidagi tarzda tuzilishi kerak: --- ``` [ixtiyoriy kontekst]: [ixtiyoriy tana (body)] [ixtiyoriy so'ngi qism(lar) (footer(s))] ``` ---
Commit kutubxonangiz foydalanuvchilariga mohiyatni yetkazish uchun quyidagi tarkibiy elementlarni o'z ichiga olishi kerak: 1. **fix:** `fix` commit _turi_ - kodingizdagi xatoni tuzatadi (bu, Semantik Versiyalashtiruvdagi [`PATCH`](https://semver.org/#summary) bilan mos keladi). 2. **feat:** `feat` commit _turi_ - kodingizga yangi xususiyat qo'shadi. (bu, Semantik Versiyalashtiruvdagi [`MINOR`](https://semver.org/#summary) bilan mos keladi). 3. **BREAKING CHANGE:** `BREAKING CHANGE` nomli _footerga_ ega yoki `[ixtiyoriy kontekst]` dan so'ng undov belgisi (`!`) bilan tugallanadigan commit - amaldagi API ga nomutanosib o'zgartirish kiritadi (bu, Semantik Versiyalashtiruvdagi [`MAJOR`](https://semver.org/#summary) bilan mos keladi). `BREAKING CHANGE` har qanday _tur_ dagi commitlarning bir qismi bo'lishi mumkin. 4. Yuqorida ko'rsatilgan _tur_ lardan boshqalariga ham ruxsat beriladi, masalan [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) ([Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) konventsiyasi asosida) `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` , va boshqalar. 5. `BREAKING CHANGE: ` dan boshqa muqobil footerlardan foydalanish, hamda [git trailer formatiga](https://git-scm.com/docs/git-interpret-trailers) amal qilish mumkin. Boshqa _turlar_ `Conventional Commits` tomonidan talab qilinmaydi va Semantik versioning ga hech qanday aniq ta'sir ko'rsatmaydi (faqatgina `BREAKING CHANGE` ni o'z ichiga olishmasa). Commit turiga, qo'shimcha `kontext` qo'shish uchun _turdan_ so'ng qavsdan foydalaning, masalan, `feat(parser): add ability to parse arrays` ## Namunalar ### `BREAKING CHANGE` footer ga hamda ta'rifga ega commit xabarlari ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### `BREAKING CHANGE` ni ifodalovchi `!` belgisiga ega commit xabarlari ``` feat!: send an email to the customer when a product is shipped ``` ### `BREAKING CHANGE` ni ifodalovchi `!` belgisi hamda _kontekstga_ ega commit xabarlari ``` feat(api)!: send an email to the customer when a product is shipped ``` ### `BREAKING CHANGE` ni ifodalovchi `!` belgi va _footerga_ ega commit xabarlari ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### _tana(body)_ siz commit xabarlari ``` docs: correct spelling of CHANGELOG ``` ### _kontekst_ ga ega commit xabarlari ``` feat(lang): add polish language ``` ### Bir nechta paragrafli _tana(body)_ va bir nechta _footer_ ga ega commit xabalari ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Spesifikatsiya Ushbu hujjatdagi «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» kalit so'zlari [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) da ko'rsatilgandek talqin qilinishi kerak. 1. Commitlar ot so'z turkumiga oid, `feat`, `fix` va shunga o'xshash so'z bilan boshlanishi shart(MUST). Undan keyin ixtiyoriy kontekst (OPTIONAL), undov belgisi (`!`) (OPTIONAL), va undan so'ng ikki nuqta (`:`) hamda bo'sh joy (` `) joydan iborat bo'lishligi talab etiladi (REQUIRED). 2. Agar commit ilovangiz yoki kutubxonangizga yangi xususiyat qo'shsa, `feat:` _turidan_ foydalanishingiz shart (MUST). 3. Agar commit ilovangiz yoki kutubxonangizdagi muommoni bartaraf qilsa, `fix:` _turidan_ foydalanishingiz shart (MUST). 4. Turdan so'ng _kontekst_ kelishi mumkin (MAY). _Kontekst_ qavslar bilan o'ralgan, kutubxonangizdagi kodlarning bir qismini tavsiflovchi ot so'z turkumiga oid so'z bo'lishligi kerak, masalan `fix(parser)`. 5. Commit haqida tavsif darhol _tur_/_kontekst_ prefiksidan keyin ikki nuqta (`:`) va bo'sh joydan (` `)keyin bo'lishi kerak (MUST). Tavsif bu kod o'zgarishlarining qisqacha xulosasidir. Masalan, `fix: array parsing issue when multiple spaces were contained in string` 6. Qisqa tavsifdan so'ng kod o'zgarishlari haqida qo'shimcha kontekstual ma'lumotlarni taqdim etuvchi tana(body) qismi taqdim etilishi mumkin (MAY). Tana(body) qismi tavsifdan keyin bitta bo'sh qatordan so'ng boshlanishi kerak (MUST). 7. Commitning tana(body) qismi ixtiyoriy bo'lib, istalgan miqdordagi paragraflardan iborat bo'lishi mumkin. (MAY) 8. _Tana(body)_ qismidan keyin 1ta bo'sh qatordan so'ng, bir yoki bir nechta _footerlar_ bo'lishligi mumkin (MAY). Har bir _footer_ so'z belgisidan iborat bo'lishi, undan keyin `:` yoki `#` ajratuvchisi, keyin matn qiymatidan iborat bo'lishligi shart (MUST) ([git trailer format](https://git-scm.com/docs/git-interpret-trailers) asosida). 9. _Footer_ tokeni uchun (` `) bo'sh joy begilising o'rniga (`-`) dan foydalanish kerak (MUST). Masalan, `Acked-by` (bu _footer_ tokenini uning ko'p paragrafli _tana_ qismidan ajratishga yordam beradi). _BREAKING CHANGE_ bundan mustasno, undan token sifatida ham foydalanish mumkin (MAY). 10. _Footerning_ qiymati ya'ni tana qismida boʻshliqlar va yangi satrlar boʻlishi mumkin (MAY) va keyingi _footer_ token/ajratuvchi juftlik kuzatilganda avvalgi _footer_ tugatilishi kerak (MUST). 11. `BREAKING CHANGE` o'zgarishlar commit xabarining _tur/kontekst_ prefiksida yoki _footer_ token qismida ko'rsatilishi kerak (MUST). 12. Agar _footerda_ `BREAKING CHANGE` bo'lsa, u katta harflardan tashkil topgan `BREAKING CHANGE` so'zlari va undan so'ng ikki nuqta (`:`), bo'sh joy (` `) va tavsifdan iborat bo'lishi kerak (MUST). Masalan, `BREAKING CHANGE: environment variables now take precedence over config files.` 13. Agar _tur/kontekst_ prefiksida `BREAKING CHANGE` mavjud bo'lsa, u holda ikki nuqtadan (`:`) avval undov belgisi (`!`) bo'lishligi shart (MUST)! Agar undov belgisi (`!`) ishlatilgan bo'lsa, u holda _footer_ qismida emas (MAY), balki commit xabarining `tasnif` qismida `BREAKING CHANGE` haqida ma'lumot berilishi mumkin. (SHALL) 14. Commit xabarlarida `feat` va `fix`dan boshqa turlardan foydalanish mumkin (MAY). Masalan, `docs: updated ref docs` 15. "Conventional Commits" kelishuviga asosan ishlatilayotgan so'zlar, dasturchilar tomonidan `case sensitive` bo'lmasligi kerak (MUST NOT), lekin `BREAKING CHANGE` bundan mustasno, chunki bu katta harflarda yozilishi lozim (MUST). 16. `BREAKING-CHANGE`, _footerning_ tokeni sifatida ishlatilganda, `BREAKING CHANGE` bilan sinonim bo‘lishi kerak (MUST). ## Nima uchun «Conventional Commits» dan foydalanish kerak - Avtomatik tarzda o'zgarishlar ro'yhati(CHANGELOG) yaratilishi. - Semantik versiyani avtomatik ravishda aniqlash (qo'shilgan commitlarning _turlariga_ asoslanib). - Jamoadoshlarni, ommani va boshqalarni o'zgarishlarning mohiyati haqida xabardor qilish. - `Build` hamda `Publish` jarayonlarini ishga tushirish. - Yaxshi tuzilgan commitlar tarixini o'rganish orqali, odamlarga sizning loyihalaringizga hissa qo'shishni osonlashtirish imkonini beradi. ## FAQ (Tez-tez so'raladigan savollar) ### Boshlang'ich rivojlantirish bosqichida commit xabarlari bilan qanday munosabatda bo'lish kerak? Biz, siz mahsulotni allaqachon ishlab chiqarilgan deb davom etishingizni tavsiya qilamiz. Odatda _kimdir_, garchi u sizning dastur ishlab chiquvchi hamkasbingiz bo'lsa ham, sizning dasturingizdan foydalanadi. Ular, tuzatilgan narsalar, nimalar qo'shilganligi va h.k haqida xabardor bo'lishni istaydilar. ## Commit _turi_ katta yoki kichik harflarda bo'lishi kerakmi? Sizga eng yoqqanini tanlang va unga qat'iy rioya qiling. ### Agar commit birdan ko'p commit turlariga mos keladigan bo'lsa nima qilish kerak? Iloji bo'lsa, orqaga qayting va bir nechta commitlarni yarating. `Conventional Commits`ning afzalliklaridan biri bu bizni ko'proq tashkillashtirilgan commitlar va PR (Pull Request) qilishga undash qobiliyatidir. ### Bu tez rivojlanish va tez iteratsiyaga to'sqinlik qilmaydimi? Bu tez, tartibsiz harakatni oldini oladi. Bu sizga turli hissa qo'shuvchilar bilan bir nechta loyihalar bo'ylab tez uzoq muddatli harakat qilish imkonini beradi. ### `«Conventional Commits»` dasturchilarni o'zlari bajaradigan commitlar _turlarini_ cheklashga olib kelishi mumkinmi, chunki ular tavsiya etilgan _turlarga_ ko'ra o'ylashadi? `Conventional Commits` bizni tuzatishlar (`fix: `) kabi muayyan turdagi commitlarni ko'proq qilishga undaydi. Bundan tashqari, `Conventional Commits`ning moslashuvchanligi sizning jamoangizga o'z _turlarini_ ishlab chiqishga va vaqt o'tishi bilan bu _turlarni_ o'zgartirishga imkon beradi. ### Buni Semantik versiyaga qanday aloqasi bor? `fix` _turidagi_ commitlar `PATCH` relizlariga, `feat` - `MINOR`-ga, `BREAKING CANGE` - _turidan_ qat'iy nazar - `MAJOR`-ga tarjima qilinishi kerak. ### Qanday qilib kengaytmalarimni(extensions) «Conventional Commits» spetsifikatsiyasiga moslashtirishim kerak, masalan. `@jameswomack/conventional-commit-spec`? Ushbu spetsifikatsiyaga o'z kengaytmalaringizni chiqarish uchun Semantik versiyadan foydalanishni tavsiya etamiz (va sizni ushbu kengaytmalarni yaratishga undaymiz!). ### Agar tasodifan noto'g'ri commit _turidan_ foydalansam nima qilishim kerak? #### Siz spetsifikatsiyaga tegishli, lekin to'g'ri _turdan_ foydalanmaganingizda, masalan. `feat` o'rniga `fix` Xatoni `push` yoki `releasing` qilishdan oldin, biz commitlar tarixini tahrirlash uchun `git rebase -i` dan foydalanishni tavsiya qilamiz. `Release` so'ng, tahrirlash qaysi vositalar va jarayonlardan foydalanganingizga qarab o'zgaradi. #### Spetsifikatsiyada ko'rsatilmagan _turdan_ foydalanganda. Misol uchun, `feat` o'rniga `feet` Eng yomon holatga ko'ra, agar commit `Conventional Commits` spetsifikatsiyasiga to'g'ri kelmasa, bu qiyomat degani emas. Bu shunchaki spetsifikatsiyaga asoslangan vositalar tomonidan commit o'tkazib yuborilishini anglatadi. ### Mening barcha kontributorlarim `Conventional Commits` spetsifikatsiyasidan foydalanishlari kerakmi? Yo'q! Agar siz `Git`da commitlarni birlashtirish (`squash`) usulidan foydalansangiz, loyiha maintainerlari birlashtirilgan, oddiy commit qiluvchilarning ish yukini qo'shmasdan birlashtirishi, topshiriq xabarlarini tartibga solishi mumkin. Buning uchun umumiy ish jarayoni sizning git tizimingiz avtomatik ravishda `PR` soʻrovi boʻyicha commitlarni `squash` qilish va maintainerga birlashtirish uchun tegishli git commit xabarini kiritadigan formani taqdim qilishi kerak. ### «Conventional Commits» orqali qanday qilib bekor qilingan commitlarni uzatish mumkin? Kod o'zgarishlarini bekor qilish qiyin bo'lishi mumkin: - Bir nechta commitlarni bekor qilyabsizmi? - Agar siz yangi xususiyat o'zgarishlarini bekor qilsangiz, keyingi versiya `PATCH` bo'lishi kerakmi? `Conventional Commits` bekor qilish xatti-harakatini aniqlash uchun aniq tarzda ta'riflashga urinmaydi. Buning o'rniga, biz o'zgarishlarni bekor qilish uchun o'z mantig'ini ishlab chiqishda _turlar_ va _footerlarning_ moslashuvchanligidan foydalanishni vosita mualliflariga qoldiramiz. Tavsiyalardan biri `revert` turi va qaytarilayotgan majburiyat xeshlariga (`SHA`) ishora qiluvchi _footerdan_ foydalanishdir. Masalan: ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.zh-hans.md ================================================ --- draft: false aliases: ["/zh/", "/zh-hans/"] --- # 约定式提交 1.0.0 ## 概述 约定式提交规范是一种基于提交信息的轻量级约定。 它提供了一组简单规则来创建清晰的提交历史； 这更有利于编写自动化工具。 通过在提交信息中描述功能、修复和破坏性变更， 使这种惯例与 [SemVer](http://semver.org/lang/zh-CN) 相互对应。 提交说明的结构如下所示： --- 原文： ``` [optional scope]: [optional body] [optional footer(s)] ``` 译文： ``` <类型>[可选 范围]: <描述> [可选 正文] [可选 脚注] ``` ---
提交说明包含了下面的结构化元素，以向类库使用者表明其意图： 1. **fix:** _类型_ 为 `fix` 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 [`PATCH`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 2. **feat:** _类型_ 为 `feat` 的提交表示在代码库中新增了一个功能（这和语义化版本中的 [`MINOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 3. **BREAKING CHANGE:** 在脚注中包含 `BREAKING CHANGE:` 或 <类型>(范围) 后面有一个 `!` 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 [`MAJOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 破坏性变更可以是任意 _类型_ 提交的一部分。 4. 除 `fix:` 和 `feat:` 之外，也可以使用其它提交 _类型_ ，例如 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)（基于 [Angular 约定](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)）中推荐的 `build:`、`chore:`、 `ci:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:`，等等。 - build: 用于修改项目构建系统，例如修改依赖库、外部接口或者升级 Node 版本等； - chore: 用于对非业务性代码进行修改，例如修改构建流程或者工具配置等； - ci: 用于修改持续集成流程，例如修改 Travis、Jenkins 等工作流配置； - docs: 用于修改文档，例如修改 README 文件、API 文档等； - style: 用于修改代码的样式，例如调整缩进、空格、空行等； - refactor: 用于重构代码，例如修改代码结构、变量名、函数名等但不修改功能逻辑； - perf: 用于优化性能，例如提升代码的性能、减少内存占用等； - test: 用于修改测试用例，例如添加、删除、修改代码的测试用例等。 1. 脚注中除了 `BREAKING CHANGE: ` ，其它条目应该采用类似 [git trailer format](https://git-scm.com/docs/git-interpret-trailers) 这样的惯例。 其它提交类型在约定式提交规范中并没有强制限制，并且在语义化版本中没有隐式影响（除非它们包含 BREAKING CHANGE）。

可以为提交类型添加一个围在圆括号内的范围，以为其提供额外的上下文信息。例如 `feat(parser): adds ability to parse arrays.`。 ## 示例 ### 包含了描述并且脚注中有破坏性变更的提交说明 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 包含了 `!` 字符以提醒注意破坏性变更的提交说明 ``` feat!: send an email to the customer when a product is shipped ``` ### 包含了范围和破坏性变更 `!` 的提交说明 ``` feat(api)!: send an email to the customer when a product is shipped ``` ### 包含了 `!` 和 BREAKING CHANGE 脚注的提交说明 ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### 不包含正文的提交说明 ``` docs: correct spelling of CHANGELOG ``` ### 包含范围的提交说明 ``` feat(lang): add polish language ``` ### 包含多行正文和多行脚注的提交说明 ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## 约定式提交规范 本文中的关键词 “必须（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）” ，其相关解释参考 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 。 1. 每个提交都**必须**使用类型字段前缀，它由一个名词构成，诸如 `feat` 或 `fix` ， 其后接**可选的**范围字段，**可选的** `!`，以及**必要的**冒号（英文半角）和空格。 1. 当一个提交为应用或类库实现了新功能时，**必须**使用 `feat` 类型。 1. 当一个提交为应用修复了 bug 时，**必须**使用 `fix` 类型。 1. 范围字段**可以**跟随在类型字段后面。范围**必须**是一个描述某部分代码的名词，并用圆括号包围，例如： `fix(parser):` 1. 描述字段**必须**直接跟在 <类型>(范围) 前缀的冒号和空格之后。 描述指的是对代码变更的简短总结，例如： _fix: array parsing issue when multiple spaces were contained in string_ 。 1. 在简短描述之后，**可以**编写较长的提交正文，为代码变更提供额外的上下文信息。正文**必须**起始于描述字段结束的一个空行后。 1. 提交的正文内容自由编写，并**可以**使用空行分隔不同段落。 1. 在正文结束的一个空行之后，**可以**编写一行或多行脚注。每行脚注都**必须**包含 一个令牌（token），后面紧跟 `:` 或 `#` 作为分隔符，后面再紧跟令牌的值（受 [git trailer convention](https://git-scm.com/docs/git-interpret-trailers) 启发）。 1. 脚注的令牌**必须**使用 `-` 作为连字符，比如 `Acked-by` (这样有助于 区分脚注和多行正文)。有一种例外情况就是 `BREAKING CHANGE`，它**可以**被认为是一个令牌。 1. 脚注的值**可以**包含空格和换行，值的解析过程**必须**直到下一个脚注的令牌/分隔符出现为止。 1. 破坏性变更**必须**在提交信息中标记出来，要么在 <类型>(范围) 前缀中标记，要么作为脚注的一项。 1. 包含在脚注中时，破坏性变更**必须**包含大写的文本 `BREAKING CHANGE`，后面紧跟着冒号、空格，然后是描述，例如： _BREAKING CHANGE: environment variables now take precedence over config files_ 。 1. 包含在 <类型>(范围) 前缀时，破坏性变更**必须**通过把 `!` 直接放在 `:` 前面标记出来。 如果使用了 `!`，那么脚注中**可以**不写 `BREAKING CHANGE:`， 同时提交信息的描述中**应该**用来描述破坏性变更。 1. 在提交说明中，**可以**使用 `feat` 和 `fix` 之外的类型，比如：_docs: updated ref docs._ 。 1. 工具的实现必须**不区分**大小写地解析构成约定式提交的信息单元，只有 `BREAKING CHANGE` **必须**是大写的。 1. BREAKING-CHANGE 作为脚注的令牌时**必须**是 BREAKING CHANGE 的同义词。 ## 为什么使用约定式提交 * 自动化生成 CHANGELOG。 * 基于提交的类型，自动决定语义化的版本变更。 * 向同事、公众与其他利益关系者传达变化的性质。 * 触发构建和部署流程。 * 让人们探索一个更加结构化的提交历史，以便降低对你的项目做出贡献的难度。 ## FAQ ### 在初始开发阶段我该如何处理提交说明？ 我们建议你按照假设你已发布了产品那样来处理。因为通常总 *有人* 使用你的软件，即便那是你软件开发的同事们。他们会希望知道诸如修复了什么、哪里不兼容等信息。 ### 提交标题中的类型是大写还是小写? 大小写都可以，但最好是一致的。 ### 如果提交符合多种类型我该如何操作？ 回退并尽可能创建多次提交。约定式提交的好处之一是能够促使我们做出更有组织的提交和 PR。 ### 这不会阻碍快速开发和迭代吗？ 它阻碍的是以杂乱无章的方式快速前进。它助你能在横跨多个项目以及和多个贡献者协作时长期地快速演进。 ### 约定式提交会让开发者受限于提交的类型吗（因为他们会想着已提供的类型）？ 约定式提交鼓励我们更多地使用某些类型的提交，比如 `fixes`。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。 ### 这和 SemVer 有什么关联呢？ `fix` 类型提交应当对应到 `PATCH` 版本。`feat` 类型提交应该对应到 `MINOR` 版本。带有 `BREAKING CHANGE` 的提交不管类型如何，都应该对应到 `MAJOR` 版本。 ### 我对约定式提交做了形如 `@jameswomack/conventional-commit-spec` 的扩展，该如何版本化管理这些扩展呢？ 我们推荐使用 SemVer 来发布你对于这个规范的扩展（并鼓励你创建这些扩展！） ### 如果我不小心使用了错误的提交类型，该怎么办呢？ #### 当你使用了在规范中但错误的类型时，例如将 `feat` 写成了 `fix` 在合并或发布这个错误之前，我们建议使用 `git rebase -i` 来编辑提交历史。而在发布之后，根据你使用的工具和流程不同，会有不同的清理方案。 #### 当使用了 *不在* 规范中的类型时，例如将 `feat` 写成了 `feet` 在最坏的场景下，即便提交没有满足约定式提交的规范，也不会是世界末日。这只意味着这个提交会被基于规范的工具错过而已。 ### 所有的贡献者都需要使用约定式提交规范吗？ 并不！如果你使用基于 squash 的 Git 工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。 有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交，并向主管维护者提供一份表单，用以在合并时输入合适的 git 提交信息。 ### 约定式提交规范中如何处理还原（revert）提交? 还原提交（Reverting）会比较复杂：你还原的是多个提交吗？如果你还原了一个功能模块，下次发布的应该是补丁吗？ 约定式提交不能明确的定义还原行为。所以我们把这个问题留给工具开发者， 基于 _类型_ 和 _脚注_ 的灵活性来开发他们自己的还原处理逻辑。 一种建议是使用 `revert` 类型，和一个指向被还原提交摘要的脚注： ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0/index.zh-hant.md ================================================ --- draft: false aliases: ["/zh-hant/"] --- # 慣例式提交 Conventional Commits 1.0.0 ## 概述 慣例式提交規範，是一種對提交說明的輕量慣例。 它提供一些簡單的條件集合用於建立明確的提交歷史； 這能讓自動化工具更容易撰寫。 這份慣例能對應到 [SemVer](https://semver.org/lang/zh-TW/)， 透過在提交說明裡描述功能、修正以及重大變更。 提交說明應被以下方式建構： --- ``` <類型 type>[可選的作用範圍 scope]: <描述 description> [可選的正文 body] [可選的頁腳 footer] ``` ---
提交應包含以下結構性元素，用以向使用這套函式庫的使用者溝通當時的意圖： 1. **fix:** 為 `fix` _類型_ 的提交，表示對程式修正了一個臭蟲（bug）（對應到語意化版本中的 [`修訂號 PATCH`](https://semver.org/lang/zh-TW/#%E6%91%98%E8%A6%81)）。 1. **feat:** 為 `feat` _類型_ 的提交，表示對程式增加了一個功能（對應到語意化版本中的 [`次版本 MINOR`](https://semver.org/lang/zh-TW/#%E6%91%98%E8%A6%81)）。 1. **BREAKING CHANGE:** 重大變更，如果提交的頁腳以 `BREAKING CHANGE:` 開頭，或是在類型、作用範圍後有 `!`，代表包含了重大 API 變更（對應到語意化版本中的 [`主版本 MAJOR`](https://semver.org/lang/zh-TW/#%E6%91%98%E8%A6%81)）。 重大變更可以是任何 _類型_ 提交的一部分。 1. 其他: 除 `fix:` 與 `feat:` 以外，其他的提交 _類型_ 也是被允許的，例如 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (基於 [Angular 慣例](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) 中推薦的 `chore:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` 以及更多。 我們也推薦對那些沒有增加新功能或是修正臭蟲而是改善目前實作的提交使用 `improvement`。 請注意，這些類型在慣例式提交規範中並不是強制性的，且在語意化版本中也沒有隱含的作用 (除非它們包含 BREAKING CHANGE)。
1. 除了 `fix:` 與 `feat:` 之外也允許其他的 _類型_ ，如（基於 [Angular 慣例](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)的）[@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) 推薦使用 `build:` 與 `chore:`、 `ci:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:`、等其他。 1. 也可以使用 `BREAKING CHANGE: <描述>` 之外的 _頁腳_ ，並遵守類似 [git trailer format](https://git-scm.com/docs/git-interpret-trailers) 的慣例。 追加類型並不被慣例式提交所束縛，並且不對語義化版本有任何隱藏的影響。（但若包含 BREAKING CHANGE 則不在此限。）

提交的類型可以在括號內給予作用範圍，以提供額外的脈絡資訊。例如：`feat(parser): add ability to parse arrays`。 ## 範例 ### 包含描述以及頁腳有重大變更的提交說明 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 包含用以提示重大變更的 `!` 的提交說明 ``` feat!: send an email to the customer when a product is shipped ``` ### 包含作用範圍和提示重大變更的 `!` 的提交說明 ``` feat(api)!: send an email to the customer when a product is shipped ``` ### 包含 `!` 以及頁腳有重大變更的提交說明 ``` feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ### 不包含正文的提交說明 ``` docs: correct spelling of CHANGELOG ``` ### 包含作用範圍的提交說明 ``` feat(lang): add polish language ``` ### 正文有多段落以及有多個頁腳的提交說明 ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## 規範 在本文中使用的關鍵字：MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY、以及 OPTIONAL 應以 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 為參考解釋。 1. 每個提交最前面「必須 MUST」要有類型，類型由名詞組成，例如：`feat`、`fix` 等，後接上「可選的 OPTIONAL」作用範圍以及「必要的 REQUIRED」一個冒號與空格。 1. 當提交一個新功能到你的應用程式或是函式庫時，「必須 MUST」使用 `feat` 類型。 1. 當提交一個臭蟲修正到你的應用程式時，「必須 MUST」使用 `fix` 類型。 1. 類型之後「可以 MAY」加上作用範圍。個別作用範圍「必須 MUST」由一個描述程式區段的名詞所組成，並用括號包覆。例如： `fix(parser):` 1. 描述「必須 MUST」緊鄰在類型／作用範圍後的冒號與空格。 描述是對於程式碼修改的簡短總結，如 _fix: array parsing issue when multiple spaces were contained in string_ 。 1. 在簡短的描述後「可以 MAY」加上更長的提交正文，提供關於對程式碼變更的額外脈絡資訊。正文「必須 MUST」在描述後的一個空行之後開始。 1. 提交正文為自由格式，並「可以 MAY」有數個以換行字元區分的段落。 1. 在正文後「可以 MAY」有一個或多個頁腳，頁腳在正文後空行之後開始。 每個頁腳「必須 MUST」包含一個符記 (token) ，並接着以 `:` 或 `#` 分隔，再緊鄰一個字串值。 （本處靈感係源自於 [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)。） 1. 頁腳的符記「必須 MUST」使用 `-` 作為空白字元，如 `Acked-by` （這有助於區分出頁腳與多段落的正文）。 但 `BREAKING CHANGE` 則為例外，且也「可以 MAY」作為符記使用。 1. 頁腳的值「可以 MAY」包含空白與換行，解析時「必須 MUST」在遇到下一組有效的符記／分隔時停止。 1. 重大變更「必須 MUST作為提交中的類型／作用範圍的前綴，或是在頁腳中作為一個段落存在。 1. 若放置於頁腳，重大變更「必須 MUST」維持大寫文字 BREAKING CHANGE，而後緊鄰一個分號、空白、並接着描述。如： _BREAKING CHANGE: environment variables now take precedence over config files_ 。 1. 若作為類型／作用範圍的前綴，重大變更「必須 MUST」以一個 `!` 識別，並緊鄰於 `:` 之前。若使用 `!`， 頁腳段落的 `BREAKING CHANGE:` 則「可以 MAY」被省略，且提交說明「應當 SHALL」用來描述重大變更。 1. 除了 `feat` 與 `fix` 以外的類型「可以 MAY」被用於提交訊息內，如： _docs: updated ref docs_ 。 1. 組成慣例式提交資訊的單位在實作時除了大寫的 `BREAKING CHANGE` 外，「禁止 MUST NOT」區分大小寫。 1. 在作為頁腳符記時，BREAKING-CHANGE「必須 MUST」與 BREAKING CHANGE 視為相同的。 ## 為何要使用慣例式提交 * 自動產生修改日誌 (Changelog)。 * 基於提交的類型，自動決定語意化版本的升級。 * 向同事、公眾以及其他的利益相關者傳達變化的過程。 * 觸發建置與發布流程。 * 讓大家探索更有結構的提交歷史，使你的專案更容易被貢獻。 ## FAQ ### 在初始的開發階段，我該如何處理提交說明？ 我們建議你可以就像是產品已經發行的那樣去執行。因為通常都會 *有人* 使用你的軟體，即使是你的軟體開發的同事們，他們會希望知道修正了什麼以及有什麼重大變更等資訊。 ### 提交標題中的類型應該要用大寫還是小寫？ 大小寫都可以，但是最好是一致的。 ### 當提交符合一或多種提交類型，我應該怎麼做？ 退回並盡可能切成多個提交。慣例式提交的一個好處就是它能夠促使我們做更有組織的提交與拉取請求 (PR, Pull Request)。 ### 這不會阻礙快速開發與快速迭代嗎？ 它阻礙用非組織化的方式快速前進。它幫助你長期能在橫跨多個專案與多個貢獻者協作時都能快速前進。 ### 慣例式提交會讓開發者受限於提交的類型，因為他們會用已提供的類型去思考嗎？ 慣例式提交鼓勵我們多使用某些類型的提交，例如 `fixes`。除此之外，慣例式提交的彈性也允許你的團隊使用自己的類型，以及隨時間推移更改這些類型。 ### 這與 SemVer 有什麼關係呢？ `fix` 類型的提交應該對應到 `PATCH` 發行版。`feat` 類型的提交應該對應到 `MINOR` 發行版。含有 `BREAKING CHANGE` 的提交，無論是什麼類型，都應該要對應到 `MAJOR` 發行版。 ### 我對慣例式提交做了擴充 (例如：`@jameswomack/conventional-commit-spec`)，我該如何管理這些擴充的版本呢？ 我們推薦使用 SemVer 來發行你對這份規範的擴充 (並且也鼓勵你做些擴充！) ### 如果我不小心用錯提交類型，該怎麼辦？ #### 當你使用規範中但是錯誤的類型，例如：將 `feat` 寫成 `fix` 在合併或是發行這個錯誤之前，我們推薦使用 `git rebase -i` 來編輯提交歷史。 而在發行之後，根據你使用的工具與流程，會有不同的清理方式。 #### 當你使用 *非* 規範中的類型時，例如：將 `feat` 寫成 `feet` 最糟狀況下，即使提交沒有符合慣例式提交的規範，也不會是世界末日。它僅意味著這個提交將會被基於這個規範的工具略過。 ### 所有的貢獻者都需要使用慣例式提交的規範嗎？ 不用！如果你使用的是基於 squash 的 Git 工作流程，主維護者可以在合併時清理提交說明，因此這不會對一般的提交者產生額外的負擔。 有一種常見的工作流程是讓 git 系統自動從 pull request 中 squash 出提交，然後提供一份表單給主維護者，用以在合併的時候輸入合適的 git 提交說明。 ### 慣例式提交要如何處理回退提交 (revert commit)？ 回退程式碼可能非常複雜：你是回退了多個提交嗎？如果你回退了一個功能，那麼下一個發行版應該要是修正檔嗎？ 慣例式提交沒有強制定義回退的行為。反而，我們將這個問題留給工具的作者，靈活運用 _類型_ 以及 _頁腳_ 來開發處理回退的邏輯。 其中一個推薦的方法時使用 `revert` 類型，並在頁腳中參照到被回退的 SHA 雜湊： ``` revert: let us never again speak of the noodle incident Refs: 676104e, a215868 ``` ================================================ FILE: content/v1.0.0-beta/index.it.md ================================================ --- draft: false --- # Commit Convenzionali 1.0.0-beta ## Riepilogo Da maintainer di codice open source, devo poter scrivere messaggi standardizzati per i commit ed eseguire lo squash dei feature branch nel `master`. I messaggi dei commit dovrebbero seguire la seguente struttura: --- ``` [contesto opzionale]: [corpo opzionale] [piè di pagina opzionale] ``` ---
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicarne l'intento al consumatore della libreria: 1. **fix:** un commit di _tipo_ `fix` risolve un errore nel codice (correlato al [`PATCH`](http://semver.org/#summary) in un versionamento semver). 1. **feat:** un commit di _tipo_ `feat` introduce una nuova funzionalità al codice (correlato al [`MINOR`](http://semver.org/#summary) in un versionamento semver). 1. **BREAKING CHANGE:** un commit che contiente il testo `BREAKING CHANGE:` all'inizio delle sezioni opzionali _corpo_ o _piè di pagina_, introduce una breaking API change (correlato al [`MAJOR`](http://semver.org/#summary) in un versionamento semver). Una _breaking change_ può essere parte di entrambi i _tipi_ `fix:` w `feat:`.
Un _contesto_ potrebbe essere aggiunto al _tipo_ di commit, al fine di offrire ulteriori informazioni contestuali. Da aggiungere tra delle parentesi tonde, Es: `feat(parser): add ability to parse arrays`. Sono ammessi altri _tipi_ oltre `fix:` e `feat:`, ad esempio [la convenzione Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) raccomanda `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, ma questi non sono coperti da questa specifica. ## Introduzione Nello sviluppo software, secondo la mia esperienza, gli errori sono spesso introdotti ai limiti tra le applicazioni. I test unitari vanno benissimo per le interazioni che i mantenitori open source conoscono, ma non fanno un ottimo lavoro nel catturare tutti i modi interessanti, spesso inaspettati, con i quali la comunità utilizza una libreria. Solamente chi ha visto la propria applicazione restituire errori 500 dopo aver aggiornato una dipendenza ad una nuova versione patch, sa quanto sia importante una cronologia di commit facilmente leggibile (e nel migliore dei casi [un changlelog ben mantenuto](http://keepachangelog.com/en/0.3.0/)) per il processo di investigazione che dovrà affrontare. La specifica per commit convenzionali propone l'introduzione di una convenzione facilmente applicabile ai messaggi dei commit. Questa convenzione legata al [SemVer](http://semver.org), chiede ai sviluppatori software di descrivere nei messaggi dei commit qualsiasi feature, fix e breaking change loro abbiano fatto. Introducendo questa convenzione, si crea un linguaggio comune che rende più semplice rimuovere errori tra progetti. ## Specifica Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DEVE iniziare con un _tipo_, il quale consiste in un sostantivo, `feat`, `fix`, etc., seguito dai due punti ed uno spazio. 1. Il _tipo_ `feat` DEVE essere usato quando un commit aggiunge una funzionalità all'applicazione o libreria. 1. Il _tipo_ `fix` DEVE essere usato quando un commit corregge un errore all'applicazione o libreria. 1. Un _contesto_ opzionale POTREBBE essere fornito dopo il _tipo_. Un _contesto_ rappresenta una sezione dell'applicazione o libreria, il contentuo va racchiusa tra delle parentesi. Es: `fix(parser):` 1. Una _descrizione_ DEVE seguire immediatamente il _tipo_ (con eventuale _contesto_). Per _descrizione_ si intende una breve spiegazione della pull request. Es: _fix: array parsing issue when multiple spaces were contained in string._ 1. Un _corpo_ del commit più lungo POTREBBE essere aggiunto dopo una breve _descrizione_. Il _corpo_ DEVE inizare dopo una linea vuota dalla _descrizione_. 1. Un _piè di pagina_ POTREBBE essere aggiunto inserendo una linea vuota dopo il _corpo_. Il _piè di pagina_ DOVREBBE contenere ulteriori informazioni riguardo la pull request (come le issue che risolve, Es: `fixes #13, #5`). 1. Una _breaking changes_ DEVE essere indicata all'inizio delle sezioni _piè di pagina_ o del _corpo_ del commit. Una _breaking change_ DEVE essere scritta in maiuscolo `BREAKING CHANGE`, seguita dai due punti ed uno spazio. 1. Una descrizione DEVE essere aggiunta dopo il testo `BREAKING CHANGE: `, descrivendo il cambiamento delle API. Es: _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Un commit POTREBBE utilizzare altri _tipi_ al di fuori di `feat` e `fix` nel messagio. ## Perchè utilizzare commit convenzionali * CHANGELOG generati automaticamente. * Determina automaticamente l'incremento di un versionamento semver (basandosi sui tipi di commit utilizzati). * Comunica la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate. * Attiva build e processi di rilascio. * Rendi più semplice alle persone contribuire al tuo progetto, dando la possibilità di espolrare una cronologia di commit più strutturata. ## FAQ ### Come dovrei comportarmi con i messaggi dei commit nella fase iniziale del progetto? Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente *qualcuno*, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc. ### Cosa faccio se il tipo di commit è conforme a più di un tipo? Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request più organizzati. ### Non disincoraggia sviluppo ed iterazioni rapidi? Disingoraggia farlo in una maniere disorgaizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori. ### Potrebbe Commit Convenzionali limitare gli sviluppatori a fare solamente alcuni tipi commit perchè penseranno nei tipi forniti dalla specifica? Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo. ### Come si collega a SemVer? I commit di tipo `fix` dovrebbero essere traducibili ai rilasci `PATCH`. I commit di tipo `feat` dovrebbero essere traducibili ai rilasci `MINOR`. I commit con `BREAKING CHANGE`, indipentemente dal tipo, dovrebbero essere traducibili ai rilasci `MAJOR`. ### Come dovrei versionare le mie estensioni per la specifica Commit Convenzionali? (Es: `@jameswomack/conventional-commit-spec`) Raccomandiamo l'utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!) ### Cosa faccio se accidentalmente utilizzo un tipo di commit sbagliato? #### Quando usi un tipo della specifica ma non quello giusto (Es: `fix` invece di `feat`) Se ancora devi creare il merge o il rilascio dell'errore, raccomandiamo l'utilizzo di `git rebase -i` per riscrivere la cronologia dei commit. Nel caso ti abbia già rilasciato questa correzzione dipende dai tool e processi che usi. #### Quando usi un tipo *non* della specifica (Es: `feet` invece di `feat`) Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica. ### Devono tutti i contributori seguire la specifica Commit Convenzionali? No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato. ================================================ FILE: content/v1.0.0-beta/index.md ================================================ --- draft: false --- # Conventional Commits 1.0.0-beta ## Summary As an open-source maintainer, squash feature branches onto `master` and write a standardized commit message while doing so. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in semantic versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning). 1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning). A breaking change can be part of either a `fix:` or `feat:` _type_ commit.
A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): adds ability to parse arrays`. Commit _types_ other than `fix:` and `feat:` are allowed, for example [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) recommends `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, but these tags are not mandated by the conventional commits specification. ## Introduction In software development, it's been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that an open-source maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use. Anyone who has upgraded to a new patch version of a dependency, only to watch their application start throwing a steady stream of 500 errors, knows how important a readable commit history (and [ideally a well maintained CHANGELOG](http://keepachangelog.com/en/0.3.0/)) is to the ensuing forensic process. The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with [SemVer](http://semver.org), asking software developers to describe in commit messages, features, fixes, and breaking changes that they make. By introducing this convention, we create a common language that makes it easier to debug issues across project boundaries. ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by a colon and a space. 1. the type `feat` MUST be used when a commit adds a new feature to your application or library. 1. the type `fix` MUST be used when a commit represents a bug fix for your application. 1. an optional scope MAY be provided after a type. A scope is a phrase describing a section of the codebase enclosed in parenthesis, e.g., `fix(parser):` 1. A description MUST immediately follow the type/scope prefix. The description is a short description of the pull request, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. A longer commit body MAY be provided after the short description. The body MUST begin one blank line after the description. 1. A footer MAY be provided one blank line after the body. The footer SHOULD contain additional meta-information about the pull-request (such as the issues it fixes, e.g., `fixes #13, #5`). 1. Breaking changes MUST be indicated at the very beginning of the footer or body section of a commit. A breaking change MUST consist of the uppercase text `BREAKING CHANGE`, followed by a colon and a space. 1. A description MUST be provided after the `BREAKING CHANGE: `, describing what has changed about the API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. types other than `feat` and `fix` MAY be used in your commit messages. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've an already released product. Typically *somebody*, even if its your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### What do I do if the commit conforms to more than one of the commit types? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the conventional commit specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the conventional commit specification? No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ================================================ FILE: content/v1.0.0-beta/index.pl.md ================================================ --- draft: false --- # Konwencjonalne Commity 1.0.0-beta ## Streszczenie Jako opiekun open-sourcowego kodu, spłaszczaj (squashuj) gałęzie funkcyjne (featurowe) do gałęzi głównej - `master` oraz pisz ustandaryzowane opisy dostarczeń (commitów). Opis dostarczenia powinien wyglądać następująco: --- ``` [opcjonalny zakres]: [opcjonalne ciało wiadomości] [opcjonalna stopka wiadomości] ``` ---
Wiadomość zawiera następujące strukturalne elementy po to, aby zakomunikować intencje do użytkowników Twojej biblioteki: 1. **fix:** dostarczenie _typu_ `fix` naprawia błąd obecny w Twoim kodzie (powiązane z [`PATCH`](http://semver.org/#summary) w wersjonowaniu semantycznym). 1. **feat:** dostarczenie _typu_ `feat` wprowadza nowe funkcje do Twojej biblioteki (powiązane z [`MINOR`](http://semver.org/#summary) w wersjonowaniu semantycznym). 1. **BREAKING CHANGE:** dostarczenie, które posiada tekst `BREAKING CHANGE:` na początku jego opcjonalnego ciała bądź stopki wprowadza zmianę łamiącą kompatybilność API (powiązane z [`MAJOR`](http://semver.org/#summary) w wersjonowaniu semantycznym). Zmiana łamiąca kompatybilność wsteczną może być elementem zmian _typu_, `fix:` lub `feat:`.
Przy typie dostarczenia może zostać podany zakres w celu dostarczenia dokładniejszej informacji o kontekście dostarczenia. Zawiera się on w nawiasach następujących bezpośrednio po typie, np. `feat(parser): dodano możliwość parsowania list`. Wiadomości _typu_ innego niż `fix:` oraz `feat:` są dopuszczalne, na przykład [konwencja Angulara](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) poleca `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, jednak tagi te nie są respektowane przez specyfikacje konwencjonalnych Commitów. ## Wprowadzenie Podczas rozwoju oprogramowania zauważyłem, że błędy często występują na granicy pomiędzy aplikacjami. Testy jednostkowe doskonale zdają egzamin w przypadkach, o których opiekun biblioteki pomyślał, jednak sposoby, w jakich oprogramowanie zostanie użyte przez społeczność często, choć interesujące mogą być nie do pomyślenia. Tutaj testy jednostkowe niezbyt zdają egzamin. Każdy, kto kiedykolwiek zaktualizował zależność swojej aplikacji, chociażby o jedną wersję _patch_, tylko po to, aby zobaczyć, jak jego aplikacja zaczyna rzucać 500 błędami, wie, jak ważną rolę stanowi czytelna historia dostarczeń (oraz dodatkowo [dobrze zarządzany DZIENNIK ZMIAN](http://keepachangelog.com/en/0.3.0/)) podczas naprawy. Specyfikacja Konwencjonalnych Commitów proponuje wprowadzenie ustandaryzowanej, lekkiej konwencji wykorzystującej wiadomości w dostarczeniach. Konwencja ta łączy się z [SemVer](http://semver.org), nakazując deweloperom opisywanie w wiadomościach podczas dostarczania jakie funkcje wprowadzają, co naprawiają oraz jakie niekompatybilne wstecz zmiany wnoszą. Wprowadzając tę konwencję, tworzymy powszechny język, który pozwala na dużo łatwiejsze wyłapywanie błędów występujących na granicy projektu z jego zależnościami. ## Specyfikacja Następujące terminy “MUSI” (“MUST”), “NIE MOŻE” (“MUST NOT”), “WYMAGANY” (“REQUIRED”), “MA BYĆ” (“SHALL”), “NIE BĘDZIE” (“SHALL NOT”), “POWINIEN” (“SHOULD”), “NIE POWINIEN” (“SHOULD NOT”), “ZALECANY” (“RECOMMENDED”), “MOŻE” (“MAY”) oraz “OPCJONALNY” (“OPTIONAL”) pojawiające się w tym dokumencie rozumiane są zgodnie z ich opisem na stronie: [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Dostarczenie MUSI być poprzedzone typem, który składa się z rzeczownika, np. `feat`, `fix`, itp., oraz następującymi bezpośrednio po nim dwukropka oraz spacji. 1. Typ `feat` MUSI być użyt, gdy dostarczenie dodaje nową funkcję do Twojej aplikacji bądź bibliteki. 1. Typ `fix` MUSI być użyty, kiedy dostarczenie naprawia błąd w Twojej aplikacji. 1. Opcjonalny zakres MOŻE być podany po typie. Zakres jest to fraza opisująca obszar kodu zawarta w nawiasach okrągłych, np., `fix(parser):` 1. Opis MUSI występować zaraz po przedrostku typu/zakresu. Opis jest to krótka notka stanowiąca o treści dostarczenia, np., _fix: problem podczas parsowania listy, kiedy string zawierał wiele spacji._ 1. Dłuższe ciało wiadomośći MOŻĘ być podane po krótkim opisie. Ciało MUSI zaczynać się jedną pustą linię po opisie. 1. Stopka MOŻE być podane jedną linię za ciałem wiadomości. Stopka POWINNA zawierać dodatkowe informacje odnośnie zgłoszeń błędów lub propozycji funkcjonalności, które rozwiąznuje, np. `fixes #13, #5`. 1. Zmiany niekompatybilne wstecz MUSZĄ być zaznaczone na samym początku sekcji ciała wiadmości lub stopki. Informacja o niekompatybilności MUSI zawierać tekst `BREAKING CHANGE`, wraz z następującymi po nim dwukropkiem oraz spacją. 1. Po tekście `BREAKING CHANGE: ` MUSI następować opis mówiący o tym, co zostało zmienione w kodzie w sposób, który niszczy kompatybilność wstecz, np. _BREAKING CHANGE: zmienne środowiskowe mają teraz większy priorytet niż pliki konfiuguracyjne._ 1. Typy inne niż `feat` oraz `fix` MOGĄ być użyte w wiadomościach Twoich dostarczeń. ## Dlaczego używać Konwencjonalnych Commitów * Automatycznie generowany DZIENNIK ZMIAN. * Automatycznie wykrywana zmiana semantycznej zmiany wersji (określana na podstawie typów dostarczonych zmian) * Komunikowanie zmian członkom zespołu, publice, oraz innym zainteresowanym. * Wyzywalanie procesów budowania oraz publikacji. * Łatwiejsze włączenie się w rozwój kodu przez ludzi z zewnątrz poprzez pozwolenie im na przeglądanie bardziej zorganizowanej historii dostarczeń. ## FAQ ### Jak powinienem radzić sobie z wiadomościami dostarczeń w fazie początkowej rozwoju kodu? Polecamy, żebyś postępował tak, jakby Twój produkt już został wydany. Zazwyczaj *ktoś*, nawet jeśli jest to Twój kolega z zespołu, już używa Twojego oprogramowania. Będzie chciał wiedzieć, co zostało naprawione, co nie działa itp. ### Co powinienem zrobić, jeśli dostarczenie pasuje do więcej niż jednego typu? Wróć się i stwórz więcej dostarczeń, jeśli to tylko możliwe. Częściową korzyścią z Konwencjonalnych Commitów jest zdolność do tworzenia kodu w bardziej zorganizowany sposób. ### Czy takie podejście nie zniechęca do szybkiego rozwoju oraz szybkich iteracji? Zniechęca do szybkiego poruszania się do przodu w niezorganizowany sposób. Pozwala Ci na szybkie posuwanie się do przodu w wielu projektach oraz różnorodnych deweloperów. ### Czy Konwencjonalne Commity mogą prowadzić do zmniejszenia ilości typów dostarczanych przez deweloperów, ponieważ będą myśleć w przestrzeni wymienionych typów? Konwencjonalne Commity zachęcają do tworzenia większej ilości dostarczeń danego typu, np. napraw. Z innego punktu widzenia, elastyczność Konwencjonalnych Commitów pozwala Twojemu zespołowi stworzyć własne typy oraz zmieniać je z biegiem czasu. ### Jak jest to powiązane z SemVer? Wiadomości typu `fix` powinny być traktowane tak jak `PATCH`. Wiadomości typu `feat` tak jak `MINOR`, natomiast dostarczenia zawierające `BREAKING CHANGE`, bez względu na typ, powinny być traktowane jak `MAJOR`. ### Jak powinienem wersjonować moje rozszerzenia zgodnie ze specyfikacją Konwencjonalnych Commitów, np. `@jameswomack/conventional-commit-spec`? Zalecamy używanie SemVer do wydawania własnych rozszerzeń do tej specyfikacji (oraz zachęcamy do tworzenia tych rozszerzeń!). ### Co powinienem zrobić, jeśli przypadkowo użyje błędnego typu dostarczenia? #### Jeśli użyłeś typu, który znajduje się w specyfikacji, ale nie jest poprawny, np. `fix` zamiast `feat` Przed dostarczeniem i wydaniem pomyłki, polecamy użyć `git rebase -i` w celu zmienienia historii dostarczeń. Zmiana po dostarczeniu zależy od narzędzi oraz procesów, których używasz. #### Jeśli użyłeś typu, który *nie* znajduje się w specyfikacji, np. `feet` zamiast `feat` W najgorszym przypadku - to nie koniec świata, jeśli dostarczenie niespełniające specyfikacji Konwencjonalnych Commitów zostanie wprowadzone. Po prostu znaczy to, że będzie pominięty przez narzędzia bazujące na specyfikacji. ### Czy wszyscy moi kontrybutorzy muszą używać specyfikacji Konwencjonalnych Commitów? Nie! Jeśli używasz trybu bazującego na spłaszczaniu historii dostarczeń, wtedy główni opiekunowie projektu mogą posprzątać wiadomości podczas dostarczania. Takie podejście nie narzuca żadnego obowiązku na osoby dostarczające od czasu do czasu. Powszechnym podejściem jest używanie automatycznego spłaszczania historii dostarczeń z pull requestóœ oraz wyświetlenie formularza osobie dostarczającej w celu wypełnienia wiadomości poprawną treścią. ================================================ FILE: content/v1.0.0-beta/index.zh-hans.md ================================================ --- draft: false --- # 约定式提交 1.0.0-beta ## 概述 开源维护者在将特性分支合并入 `master` 时，可编写标准化的提交说明。 提交说明的结构如下所示： --- ``` <类型>[可选的作用域]: <描述> [可选的正文] [可选的页脚] ``` ---
提交说明包含了下面的结构化元素，以向类库使用者表明其意图： 1.**fix:** _类型_ 为 `fix` 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 [`PATCH`](http://semver.org/#summary) 相对应）。 1.**feat:** _类型_ 为 `feat` 的提交表示在代码库中新增了一个功能（这和语义化版本中的 [`MINOR`](http://semver.org/#summary) 相对应）。 1.**BREAKING CHANGE:** 在可选的正文或页脚的起始位置带有 `BREAKING CHANGE:` 的提交，表示引入了破坏性变更（这和语义化版本中的 [`MAJOR`](http://semver.org/#summary) 相对应）。破坏性变更可以是 `fix:` 或 `feat:` _类型_ 提交的一部分。 1.其它在 `fix:` 和 `feat:` 之外的提交 _类型_ 也都是支持的，例如 [Angular 约定](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) 中推荐使用 `docs:`、`style:`、`refactor:`、`perf:`、`test:`、`chore:`，但这些标签在约定式提交规范中并不是强制性的。
可以为提交类型添加一个围在圆括号内的作用域，以为其提供额外的上下文信息。例如 `feat(parser): add ability to parse arrays.` ## 介绍 在软件开发中，个人的经验是 bug 最常由应用间的边界引入。对单元测试而言，在所测试的交互处在开源维护者知识范围内时，它工作得很好。但在刻画社区里各种有趣而常在预料之外的使用场景时，它就显得比较糟糕了。 任何在升级新依赖 patch 版本后发现应用开始抛出稳定 500 错误流的人，都知道可读的提交历史（以及[理想条件下高质量维护的 CHANGELOG](http://keepachangelog.com/en/0.3.0/)）有多重要。 约定式的提交规范提议在提交说明的基础上，引入标准化的轻量约定。这个约定和 [SemVer](http://semver.org) 相吻合，要求开发者在提交信息中描述新特性、bug 修复和破坏性更新。 引入这一约定后，我们可以创建一种通用的语言，简化在项目边界之间调试的问题。 ## 约定式提交规范 本文档中的关键词 “必须”、“禁止”、“需要”、“应当”、“不应当”、“应该”、“不应该”、“推荐”、“可以” 和 “可选” 应按照 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 的描述解释。 1. 每个提交都**必须**使用类型字段前缀，这由一个形如 `feat` 或 `fix` 的名词组成，其后接冒号和空格。 1. 当一个提交为应用或类库实现了新特性时，**必须**使用 `feat` 类型。 1. 当一个提交为应用修复了 bug 时，**必须**使用 `fix` 类型。 1. 可选的作用域字段**可以**在类型后提供。作用域是描述代码库中某个部分的词组，封装在括号中，形如 `fix(parser):` 等。 1. 描述字段**必须**紧接在类型或作用域前缀之后。描述指的是对 pull request 的简短描述，形如 _fix: array parsing issue when multiple spaces were contained in string._ 1. 在简短描述之后，**可以**编写更长的提交正文。正文**必须**起始于描述字段结束的一个空行后。 1. 在正文结束的一个空行后，**可以**编写页脚。页脚**应当**包含额外的元信息（例如它所修复的 issue，类似 `fixse #13, #5` 等）。 1. 破坏性变更**必须**在提交的正文或脚注加以展示。一个破坏性变更**必须**包含大写的文本 `BREAKING CHANGE`，紧跟冒号和空格。 1. 在 `BREAKING CHANGE: ` 之后**必须**提供描述，以描述对 API 的变更。例如 _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 在提交说明中，**可以**使用 `feat` 和 `fix` 之外的类型。 ## 为什么使用约定式提交 * 自动化生成 CHANGELOG。 * 基于提交的类型，自动决定语义化的版本变更。 * 向同事、公众与其他利益关系人传达变化的性质。 * 触发构建和部署流程。 * 让人们更容易地探索结构化的提交历史，降低贡献项目的难度。 ## FAQ ### 如何处理初始开发阶段的提交说明？ 我们建议你按照已发布的产品那样来处理。一般情况下即便是开发者同事，也*有人*使用你的软件。他们会希望知道诸如修复了什么、哪里不兼容等信息。 ### 提交符合一或多种类型时该如何处理？ 回退并尽可能创建多次提交。约定式提交的部分好处是能够促使我们做出更有组织的提交和 PR。 ### 这不会阻碍快速的开发和迭代吗？ 它阻碍的是以杂乱无章的方式快速前进。它帮助我们在横跨长时间周期、多个项目、多个贡献者时能够保持效率。 ### 约定式提交会让开发者受限于提交的类型吗？ 约定式提交鼓励我们更多地使用某些类型的提交，比如 fixes。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。 ### 这和 SemVer 有什么关联呢？ `fix` 类型提交应当对应到 `PATCH` 版本。`feat` 类型提交应该对应到 `MINOR` 版本。带有 `BREAKING CHANGE` 的提交不管类型如何，都应该对应到 `MAJOR` 版本。 ### 我对约定式提交做了形如 `@jameswomack/conventional-commit-spec` 的扩展，该如何版本化管理这些扩展呢？ 我们推荐使用 SemVer 来发布你对于这个规范的扩展（并鼓励你创建这些扩展！） ### 如果我不小心使用了错误的提交类型，该怎么办呢？ #### 当你使用了在规范中但错误的类型时，如将 `feat` 写成了 `fix` 在合并或发布这个错误之前，我们建议使用 `git rebase -i` 来编辑提交历史。而在发布之后，根据你使用的工具和流程不同，会有不同的清理方案。 #### 当使用了 *不* 在规范中的类型时，如将 `feat` 写成了 `feet` 在最坏的场景下，即便提交没有满足约定式提交的规范，也不是世界的终结。这只意味着这个提交会被基于规范的工具错过而已。 ### 所有的贡献者都需要使用约定式提交规范吗？ 并不！如果你使用基于 squash 的 Git 工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交，向主管维护者提供表单，来在合并时输入合适的 git 提交信息。 ================================================ FILE: content/v1.0.0-beta.1/index.it.md ================================================ --- draft: false --- # Commit Convenzionali 1.0.0-beta.1 ## Riepilogo Da maintainer di codice open source, devo poter scrivere messaggi standardizzati per i commit ed eseguire lo squash dei feature branch nel `master`. I messaggi dei commit dovrebbero seguire la seguente struttura: --- ``` [contesto opzionale]: [corpo opzionale] [piè di pagina opzionale] ``` ---
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicarne l'intento al consumatore della libreria: 1. **fix:** un commit di _tipo_ `fix` risolve un errore nel codice (correlato al [`PATCH`](http://semver.org/#summary) in un versionamento semver). 1. **feat:** un commit di _tipo_ `feat` introduce una nuova funzionalità al codice (correlato al [`MINOR`](http://semver.org/#summary) in un versionamento semver). 1. **BREAKING CHANGE:** un commit che contiente il testo `BREAKING CHANGE:` all'inizio delle sezioni opzionali _corpo_ o _piè di pagina_, introduce una breaking API change (correlato al [`MAJOR`](http://semver.org/#summary) in un versionamento semver). Una _breaking change_ può essere parte di un commit di qualsiasi _tipo_. Es: I tipi `fix:`, `feat:` & `chore:` sono tutti validi.
Un _contesto_ potrebbe essere aggiunto al _tipo_ di commit, al fine di offrire ulteriori informazioni contestuali. Da aggiungere tra delle parentesi tonde, Es: `feat(parser): add ability to parse arrays`. Sono ammessi altri _tipi_ oltre `fix:` e `feat:`, ad esempio [la convenzione Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) raccomanda `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, ma questi non sono coperti da questa specifica. ## Introduzione Nello sviluppo software, secondo la mia esperienza, gli errori sono spesso introdotti ai limiti tra le applicazioni. I test unitari vanno benissimo per le interazioni che i mantenitori open source conoscono, ma non fanno un ottimo lavoro nel catturare tutti i modi interessanti, spesso inaspettati, con i quali la comunità utilizza una libreria. Solamente chi ha visto la propria applicazione restituire errori 500 dopo aver aggiornato una dipendenza ad una nuova versione patch, sa quanto sia importante una cronologia di commit facilmente leggibile (e nel migliore dei casi [un changlelog ben mantenuto](http://keepachangelog.com/en/0.3.0/)) per il processo di investigazione che dovrà affrontare. La specifica per commit convenzionali propone l'introduzione di una convenzione facilmente applicabile ai messaggi dei commit. Questa convenzione legata al [SemVer](http://semver.org), chiede ai sviluppatori software di descrivere nei messaggi dei commit qualsiasi feature, fix e breaking change loro abbiano fatto. Introducendo questa convenzione, si crea un linguaggio comune che rende più semplice rimuovere errori tra progetti. ## Specifica Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DEVE iniziare con un _tipo_, il quale consiste in un sostantivo, `feat`, `fix`, etc., seguito dai due punti ed uno spazio. 1. Il _tipo_ `feat` DEVE essere usato quando un commit aggiunge una funzionalità all'applicazione o libreria. 1. Il _tipo_ `fix` DEVE essere usato quando un commit corregge un errore all'applicazione o libreria. 1. Un _contesto_ opzionale POTREBBE essere fornito dopo il _tipo_. Un _contesto_ rappresenta una sezione dell'applicazione o libreria, il contentuo va racchiusa tra delle parentesi. Es: `fix(parser):` 1. Una _descrizione_ DEVE seguire immediatamente il _tipo_ (con eventuale _contesto_). Per _descrizione_ si intende una breve spiegazione della pull request. Es: _fix: array parsing issue when multiple spaces were contained in string._ 1. Un _corpo_ del commit più lungo POTREBBE essere aggiunto dopo una breve _descrizione_. Il _corpo_ DEVE inizare dopo una linea vuota dalla _descrizione_. 1. Un _piè di pagina_ POTREBBE essere aggiunto inserendo una linea vuota dopo il _corpo_. Il _piè di pagina_ DOVREBBE contenere ulteriori informazioni riguardo la pull request (come le issue che risolve, Es: `fixes #13, #5`). 1. Una _breaking changes_ DEVE essere indicata all'inizio delle sezioni _piè di pagina_ o del _corpo_ del commit. Una _breaking change_ DEVE essere scritta in maiuscolo `BREAKING CHANGE`, seguita dai due punti ed uno spazio. 1. Una descrizione DEVE essere aggiunta dopo il testo `BREAKING CHANGE: `, descrivendo il cambiamento delle API. Es: _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Un commit POTREBBE utilizzare altri _tipi_ al di fuori di `feat` e `fix` nel messagio. ## Perchè utilizzare commit convenzionali * CHANGELOG generati automaticamente. * Determina automaticamente l'incremento di un versionamento semver (basandosi sui tipi di commit utilizzati). * Comunica la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate. * Attiva build e processi di rilascio. * Rendi più semplice alle persone contribuire al tuo progetto, dando la possibilità di espolrare una cronologia di commit più strutturata. ## FAQ ### Come dovrei comportarmi con i messaggi dei commit nella fase iniziale del progetto? Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente *qualcuno*, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc. ### Cosa faccio se il tipo di commit è conforme a più di un tipo? Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request più organizzati. ### Non disincoraggia sviluppo ed iterazioni rapidi? Disingoraggia farlo in una maniere disorgaizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori. ### Potrebbe Commit Convenzionali limitare gli sviluppatori a fare solamente alcuni tipi commit perchè penseranno nei tipi forniti dalla specifica? Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo. ### Come si collega a SemVer? I commit di tipo `fix` dovrebbero essere traducibili ai rilasci `PATCH`. I commit di tipo `feat` dovrebbero essere traducibili ai rilasci `MINOR`. I commit con `BREAKING CHANGE`, indipentemente dal tipo, dovrebbero essere traducibili ai rilasci `MAJOR`. ### Come dovrei versionare le mie estensioni per la specifica Commit Convenzionali? (Es: `@jameswomack/conventional-commit-spec`) Raccomandiamo l'utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!) ### Cosa faccio se accidentalmente utilizzo un tipo di commit sbagliato? #### Quando usi un tipo della specifica ma non quello giusto (Es: `fix` invece di `feat`) Se ancora devi creare il merge o il rilascio dell'errore, raccomandiamo l'utilizzo di `git rebase -i` per riscrivere la cronologia dei commit. Nel caso ti abbia già rilasciato questa correzzione dipende dai tool e processi che usi. #### Quando usi un tipo *non* della specifica (Es: `feet` invece di `feat`) Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica. ### Devono tutti i contributori seguire la specifica Commit Convenzionali? No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato. ================================================ FILE: content/v1.0.0-beta.1/index.md ================================================ --- draft: false --- # Conventional Commits 1.0.0-beta.1 ## Summary As an open-source maintainer, squash feature branches onto `master` and write a standardized commit message while doing so. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in semantic versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning). 1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning). A breaking change can be part of commits of any _type_. e.g., a `fix:`, `feat:` & `chore:` types would all be valid, in addition to any other _type_.
A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): adds ability to parse arrays`. Commit _types_ other than `fix:` and `feat:` are allowed, for example [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) recommends `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, but these tags are not mandated by the conventional commits specification. ## Introduction In software development, it's been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that an open-source maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use. Anyone who has upgraded to a new patch version of a dependency, only to watch their application start throwing a steady stream of 500 errors, knows how important a readable commit history (and [ideally a well maintained CHANGELOG](http://keepachangelog.com/en/0.3.0/)) is to the ensuing forensic process. The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with [SemVer](http://semver.org), asking software developers to describe in commit messages, features, fixes, and breaking changes that they make. By introducing this convention, we create a common language that makes it easier to debug issues across project boundaries. ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by a colon and a space. 1. the type `feat` MUST be used when a commit adds a new feature to your application or library. 1. the type `fix` MUST be used when a commit represents a bug fix for your application. 1. an optional scope MAY be provided after a type. A scope is a phrase describing a section of the codebase enclosed in parenthesis, e.g., `fix(parser):` 1. A description MUST immediately follow the type/scope prefix. The description is a short description of the pull request, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. A longer commit body MAY be provided after the short description. The body MUST begin one blank line after the description. 1. A footer MAY be provided one blank line after the body. The footer SHOULD contain additional meta-information about the pull-request (such as the issues it fixes, e.g., `fixes #13, #5`). 1. Breaking changes MUST be indicated at the very beginning of the footer or body section of a commit. A breaking change MUST consist of the uppercase text `BREAKING CHANGE`, followed by a colon and a space. 1. A description MUST be provided after the `BREAKING CHANGE: `, describing what has changed about the API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. types other than `feat` and `fix` MAY be used in your commit messages. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've an already released product. Typically *somebody*, even if its your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### What do I do if the commit conforms to more than one of the commit types? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the conventional commit specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the conventional commit specification? No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ================================================ FILE: content/v1.0.0-beta.1/index.pl.md ================================================ --- draft: false --- # Konwencjonalne Commity 1.0.0-beta.1 ## Streszczenie Jako opiekun otwartych źródeł, spłaszczaj (squashuj) gałęzie funkcyjne (featurowe) do gałęzi głównej - `master` oraz pisz ustandaryzowane opisy dostarczeń (commitów). Opis dostarczenia powinien wyglądać następująco: --- ``` [opcjonalny zakres]: [opcjonalne ciało wiadomości] [opcjonalna stopka wiadomości] ``` ---
Wiadomość zawiera następujące strukturalne elementy po to, aby zakomunikować intencje do użytkowników Twojej biblioteki: 1. **fix:** dostarczenie _typu_ `fix` naprawia błąd obecny w Twoim kodzie (powiązane z [`PATCH`](http://semver.org/#summary) w wersjonowaniu semantycznym). 1. **feat:** dostarczenie _typu_ `feat` wprowadza nowe funkcje do Twojej biblioteki (powiązane z [`MINOR`](http://semver.org/#summary) w wersjonowaniu semantycznym). 1. **BREAKING CHANGE:** dostarczenie, które posiada tekst `BREAKING CHANGE:` na początku jego opcjonalnego ciała bądź stopki wprowadza zmianę łamiącą kompatybilność API (powiązane z [`MAJOR`](http://semver.org/#summary) w wersjonowaniu semantycznym). Zmiana łamiąca kompatybilność wsteczną może być elementem zmian każdego innego _typu_, np. `fix:`, `feat:` & `chore:` - wszystkie byłyby poprawne, w dodatku do każdego innego _typu_.
Przy typie dostarczenia może zostać podany zakres w celu dostarczenia dokładniejszej informacji o kontekście dostarczenia. Zawiera się on w nawiasach następujących bezpośrednio po typie, np. `feat(parser): dodano możliwość parsowania list`. Wiadomości _typu_ innego niż `fix:` oraz `feat:` są dopuszczalne, na przykład [konwencja Angulara](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) poleca `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, jednak tagi te nie są respektowane przez specyfikacje konwencjonalnych Commitów. ## Wprowadzenie Podczas rozwoju oprogramowania zauważyłem, że błędy często występują na granicy pomiędzy aplikacjami. Testy jednostkowe doskonale zdają egzamin w przypadkach, o których opiekun biblioteki pomyślał, jednak sposoby, w jakich oprogramowanie zostanie użyte przez społeczność często, choć interesujące mogą być nie do pomyślenia. Tutaj testy jednostkowe niezbyt zdają egzamin. Każdy, kto kiedykolwiek zaktualizował zależność swojej aplikacji, chociażby o jedną wersję _patch_, tylko po to, aby zobaczyć, jak jego aplikacja zaczyna rzucać 500 błędami, wie, jak ważną rolę stanowi czytelna historia dostarczeń (oraz dodatkowo [dobrze zarządzany DZIENNIK ZMIAN](http://keepachangelog.com/en/0.3.0/)) podczas naprawy. Specyfikacja Konwencjonalnych Commitów proponuje wprowadzenie ustandaryzowanej, lekkiej konwencji wykorzystującej wiadomości w dostarczeniach. Konwencja ta łączy się z [SemVer](http://semver.org), nakazując deweloperom opisywanie w wiadomościach podczas dostarczania jakie funkcje wprowadzają, co naprawiają oraz jakie niekompatybilne wstecz zmiany wnoszą. Wprowadzając tę konwencję, tworzymy powszechny język, który pozwala na dużo łatwiejsze wyłapywanie błędów występujących na granicy projektu z jego zależnościami. ## Specyfikacja Następujące terminy “MUSI” (“MUST”), “NIE MOŻE” (“MUST NOT”), “WYMAGANY” (“REQUIRED”), “MA BYĆ” (“SHALL”), “NIE BĘDZIE” (“SHALL NOT”), “POWINIEN” (“SHOULD”), “NIE POWINIEN” (“SHOULD NOT”), “ZALECANY” (“RECOMMENDED”), “MOŻE” (“MAY”) oraz “OPCJONALNY” (“OPTIONAL”) pojawiające się w tym dokumencie rozumiane są zgodnie z ich opisem na stronie: [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Dostarczenie MUSI być poprzedzone typem, który składa się z rzeczownika, np. `feat`, `fix`, itp., oraz następującymi bezpośrednio po nim dwukropka oraz spacji. 1. Typ `feat` MUSI być użyty, gdy dostarczenie dodaje nową funkcję do Twojej aplikacji bądź biblioteki. 1. Typ `fix` MUSI być użyty, kiedy dostarczenie naprawia błąd w Twojej aplikacji. 1. Opcjonalny zakres MOŻE być podany po typie. Zakres jest to fraza opisująca obszar kodu zawarta w nawiasach okrągłych, np., `fix(parser):` 1. Opis MUSI występować zaraz po przedrostku typu/zakresu. Opis jest to krótka notka stanowiąca o treści dostarczenia, np., _fix: problem podczas parsowania listy, kiedy string zawierał wiele spacji._ 1. Dłuższe ciało wiadomości MOŻE być podane po krótkim opisie. Ciało MUSI zaczynać się jedną pustą linię po opisie. 1. Stopka MOŻE być podane jedną linię za ciałem wiadomości. Stopka POWINNA zawierać dodatkowe informacje odnośnie zgłoszeń błędów lub propozycji funkcjonalności, które rozwiązuje, np. `fixes #13, #5`. 1. Zmiany niekompatybilne wstecz MUSZĄ być zaznaczone na samym początku sekcji ciała wiadomości lub stopki. Informacja o niekompatybilności MUSI zawierać tekst `BREAKING CHANGE`, wraz z następującymi po nim dwukropkiem oraz spacją. 1. Po tekście `BREAKING CHANGE: ` MUSI następować opis mówiący o tym, co zostało zmienione w kodzie w sposób, który niszczy kompatybilność wstecz, np. _BREAKING CHANGE: zmienne środowiskowe mają teraz większy priorytet niż pliki konfiguracyjne._ 1. Typy inne niż `feat` oraz `fix` MOGĄ być użyte w wiadomościach Twoich dostarczeń. ## Dlaczego używać Konwencjonalnych Commitów * Automatycznie generowany DZIENNIK ZMIAN. * Automatycznie wykrywana zmiana semantycznej zmiany wersji (określana na podstawie typów dostarczonych zmian) * Komunikowanie zmian członkom zespołu, publice, oraz innym zainteresowanym. * Wyzwalanie procesów budowania oraz publikacji. * Łatwiejsze włączenie się w rozwój kodu przez ludzi z zewnątrz poprzez pozwolenie im na przeglądanie bardziej zorganizowanej historii dostarczeń. ## FAQ ### Jak powinienem radzić sobie z wiadomościami dostarczeń w fazie początkowej rozwoju kodu? Polecamy, żebyś postępował tak, jakby Twój produkt już został wydany. Zazwyczaj *ktoś*, nawet jeśli jest to Twój kolega z zespołu, już używa Twojego oprogramowania. Będzie chciał wiedzieć, co zostało naprawione, co nie działa itp. ### Co powinienem zrobić, jeśli dostarczenie pasuje do więcej niż jednego typu? Wróć się i stwórz więcej dostarczeń, jeśli to tylko możliwe. Częściową korzyścią z Konwencjonalnych Commitów jest zdolność do tworzenia kodu w bardziej zorganizowany sposób. ### Czy takie podejście nie zniechęca do szybkiego rozwoju oraz szybkich iteracji? Zniechęca do szybkiego poruszania się do przodu w niezorganizowany sposób. Pozwala Ci na szybkie posuwanie się do przodu w wielu projektach oraz różnorodnych deweloperów. ### Czy Konwencjonalne Commity mogą prowadzić do zmniejszenia ilości typów dostarczanych przez deweloperów, ponieważ będą myśleć w przestrzeni wymienionych typów? Konwencjonalne Commity zachęcają do tworzenia większej ilości dostarczeń danego typu, np. napraw. Z innego punktu widzenia, elastyczność Konwencjonalnych Commitów pozwala Twojemu zespołowi stworzyć własne typy oraz zmieniać je z biegiem czasu. ### Jak jest to powiązane z SemVer? Wiadomości typu `fix` powinny być traktowane tak jak `PATCH`. Wiadomości typu `feat` tak jak `MINOR`, natomiast dostarczenia zawierające `BREAKING CHANGE`, bez względu na typ, powinny być traktowane jak `MAJOR`. ### Jak powinienem wersjonować moje rozszerzenia zgodnie ze specyfikacją Konwencjonalnych Commitów, np. `@jameswomack/conventional-commit-spec`? Zalecamy używanie SemVer do wydawania własnych rozszerzeń do tej specyfikacji (oraz zachęcamy do tworzenia tych rozszerzeń!). ### Co powinienem zrobić, jeśli przypadkowo użyje błędnego typu dostarczenia? #### Jeśli użyłeś typu, który znajduje się w specyfikacji, ale nie jest poprawny, np. `fix` zamiast `feat` Przed dostarczeniem i wydaniem pomyłki, polecamy użyć `git rebase -i` w celu zmienienia historii dostarczeń. Zmiana po dostarczeniu zależy od narzędzi oraz procesów, których używasz. #### Jeśli użyłeś typu, który *nie* znajduje się w specyfikacji, np. `feet` zamiast `feat` W najgorszym przypadku - to nie koniec świata, jeśli dostarczenie niespełniające specyfikacji Konwencjonalnych Commitów zostanie wprowadzone. Po prostu znaczy to, że będzie pominięty przez narzędzia bazujące na specyfikacji. ### Czy wszyscy moi kontrybutorzy muszą używać specyfikacji Konwencjonalnych Commitów? Nie! Jeśli używasz trybu bazującego na spłaszczaniu historii dostarczeń, wtedy główni opiekunowie projektu mogą posprzątać wiadomości podczas dostarczania. Takie podejście nie narzuca żadnego obowiązku na osoby dostarczające od czasu do czasu. Powszechnym podejściem jest używanie automatycznego spłaszczania historii dostarczeń z prośby wciągnięcia (pull request) oraz wyświetlenie formularza osobie dostarczającej w celu wypełnienia wiadomości poprawną treścią. ================================================ FILE: content/v1.0.0-beta.1/index.zh-hans.md ================================================ --- draft: false --- # 约定式提交 1.0.0-beta.1 ## 概述 开源维护者在将特性分支合并入 `master` 时，可编写标准化的提交说明。 提交说明的结构如下所示： --- ``` <类型>[可选的作用域]: <描述> [可选的正文] [可选的页脚] ``` ---
提交说明包含了下面的结构化元素，以向类库使用者表明其意图： 1. **fix:** _类型_ 为 `fix` 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 [`PATCH`](http://semver.org/#summary) 相对应）。 1. **feat:** _类型_ 为 `feat` 的提交表示在代码库中新增了一个功能（这和语义化版本中的 [`MINOR`](http://semver.org/#summary) 相对应）。 1. **BREAKING CHANGE:** 在可选的正文或页脚的起始位置带有 `BREAKING CHANGE:` 的提交，表示引入了破坏性变更（这和语义化版本中的 [`MAJOR`](http://semver.org/#summary) 相对应）。破坏性变更可以是任意 _类型_ 提交的一部分。对于 `fix:`、`feat:` 和 `chore:`，乃至更多其它的 _类型_ 而言，它都是有效的。 1. 其它在 `fix:` 和 `feat:` 之外的提交 _类型_ 也都是支持的，例如 [Angular 约定](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) 中推荐使用 `docs:`、`style:`、`refactor:`、`perf:`、`test:`、`chore:`，但这些标签在约定式提交规范中并不是强制性的。
可以为提交类型添加一个围在圆括号内的作用域，以为其提供额外的上下文信息。例如 `feat(parser): add ability to parse arrays.` ## 介绍 在软件开发中，个人的经验是 bug 最常由应用间的边界引入。对单元测试而言，在所测试的交互处在开源维护者知识范围内时，它工作得很好。但在刻画社区里各种有趣而常在预料之外的使用场景时，它就显得比较糟糕了。 任何在升级新依赖 patch 版本后发现应用开始抛出稳定 500 错误流的人，都知道可读的提交历史（以及[理想条件下高质量维护的 CHANGELOG](http://keepachangelog.com/en/0.3.0/)）有多重要。 约定式的提交规范提议在提交说明的基础上，引入标准化的轻量约定。这个约定和 [SemVer](http://semver.org) 相吻合，要求开发者在提交信息中描述新特性、bug 修复和破坏性更新。 引入这一约定后，我们可以创建一种通用的语言，简化在项目边界之间调试的问题。 ## 约定式提交规范 本文档中的关键词 “必须”、“禁止”、“需要”、“应当”、“不应当”、“应该”、“不应该”、“推荐”、“可以” 和 “可选” 应按照 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 的描述解释。 1. 每个提交都**必须**使用类型字段前缀，这由一个形如 `feat` 或 `fix` 的名词组成，其后接冒号和空格。 1. 当一个提交为应用或类库实现了新特性时，**必须**使用 `feat` 类型。 1. 当一个提交为应用修复了 bug 时，**必须**使用 `fix` 类型。 1. 可选的作用域字段**可以**在类型后提供。作用域是描述代码库中某个部分的词组，封装在括号中，形如 `fix(parser):` 等。 1. 描述字段**必须**紧接在类型或作用域前缀之后。描述指的是对 pull request 的简短描述，形如 _fix: array parsing issue when multiple spaces were contained in string._ 1. 在简短描述之后，**可以**编写更长的提交正文。正文**必须**起始于描述字段结束的一个空行后。 1. 在正文结束的一个空行后，**可以**编写页脚。页脚**应当**包含额外的元信息（例如它所修复的 issue，类似 `fixse #13, #5` 等）。 1. 破坏性变更**必须**在提交的正文或脚注加以展示。一个破坏性变更**必须**包含大写的文本 `BREAKING CHANGE`，紧跟冒号和空格。 1. 在 `BREAKING CHANGE: ` 之后**必须**提供描述，以描述对 API 的变更。例如 _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 在提交说明中，**可以**使用 `feat` 和 `fix` 之外的类型。 ## 为什么使用约定式提交 * 自动化生成 CHANGELOG。 * 基于提交的类型，自动决定语义化的版本变更。 * 向同事、公众与其他利益关系人传达变化的性质。 * 触发构建和部署流程。 * 让人们更容易地探索结构化的提交历史，降低贡献项目的难度。 ## FAQ ### 如何处理初始开发阶段的提交说明？ 我们建议你按照已发布的产品那样来处理。一般情况下即便是开发者同事，也*有人*使用你的软件。他们会希望知道诸如修复了什么、哪里不兼容等信息。 ### 提交符合一或多种类型时该如何处理？ 回退并尽可能创建多次提交。约定式提交的部分好处是能够促使我们做出更有组织的提交和 PR。 ### 这不会阻碍快速的开发和迭代吗？ 它阻碍的是以杂乱无章的方式快速前进。它帮助我们在横跨长时间周期、多个项目、多个贡献者时能够保持效率。 ### 约定式提交会让开发者受限于提交的类型吗？ 约定式提交鼓励我们更多地使用某些类型的提交，比如 fixes。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。 ### 这和 SemVer 有什么关联呢？ `fix` 类型提交应当对应到 `PATCH` 版本。`feat` 类型提交应该对应到 `MINOR` 版本。带有 `BREAKING CHANGE` 的提交不管类型如何，都应该对应到 `MAJOR` 版本。 ### 我对约定式提交做了形如 `@jameswomack/conventional-commit-spec` 的扩展，该如何版本化管理这些扩展呢？ 我们推荐使用 SemVer 来发布你对于这个规范的扩展（并鼓励你创建这些扩展！） ### 如果我不小心使用了错误的提交类型，该怎么办呢？ #### 当你使用了在规范中但错误的类型时，如将 `feat` 写成了 `fix` 在合并或发布这个错误之前，我们建议使用 `git rebase -i` 来编辑提交历史。而在发布之后，根据你使用的工具和流程不同，会有不同的清理方案。 #### 当使用了 *不* 在规范中的类型时，如将 `feat` 写成了 `feet` 在最坏的场景下，即便提交没有满足约定式提交的规范，也不是世界的终结。这只意味着这个提交会被基于规范的工具错过而已。 ### 所有的贡献者都需要使用约定式提交规范吗？ 并不！如果你使用基于 squash 的 Git 工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交，向主管维护者提供表单，来在合并时输入合适的 git 提交信息。 ================================================ FILE: content/v1.0.0-beta.2/index.es.md ================================================ --- draft: false --- # Commits Convencionales 1.0.0-beta.2 ## Resumen Como mantenedor de proyectos de código abierto, cuando se incorporan ramas con nuevas características en `master` al escribir un mensaje de commit estandarizado, el mensaje del commit debe estar estructurado de la siguiente forma: --- ``` [ámbito opcional]: [cuerpo opcional] [nota de pie opcional] ``` ---
El commit contiene los siguientes elementos estructurales para comunicar la intención al consumidor de la librería: 1. **fix:** un commit de _tipo_ `fix` corrige un error en la base del código (se correlaciona con [`PATCH`](http://semver.org/#summary) en el versionado semántico). 1. **feat:** un commit de _tipo_ `feat` introduce nuevas características en la base del código (se correlaciona con [`MINOR`](http://semver.org/#summary) en el versionado semántico). 1. **BREAKING CHANGE:** un commit que contiene el texto `BREAKING CHANGE:` al inicio de su cuerpo opcional o la sección de nota de pie introduce un cambio en el uso de la API (se correlaciona con [`MAJOR`](http://semver.org/#summary) en el versionado semántico). Un cambio en el uso de la API puede ser parte de commits de _tipo_. e.g., a `fix:`, `feat:` & `chore:` todos tipos válidos, adicional a cualquier otro _tipo_. 1. Otros: _tipos_ de commits distintos a `fix:` y `feat:` están permitidos, por ejemplo [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (basado en [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recomienda `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` y otros. También recomendamos `improvement` para commits que mejorar una implementación actual sin añadir nuevas características ni corregir errores. Tenga presente que estos tipos no son impuestos por la especificación de commits convencionales y no tienen efecto implícito en el versionado semántico (a menos que incluyan el texto BREAKING CHANGE, lo cual NO es recomendado).
Se puede agregar un ámbito al _tipo_ de commit para proveer información contextual adicional y se escribe entre paréntesis, e.g., `feat(parser): add ability to parse arrays`. ## Ejemplos ### Mensaje de commit con descripción y cambio en el uso de la API en el cuerpo ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Mensaje de commit sin cuerpo ``` docs: correct spelling of CHANGELOG ``` ### Mensaje de commit con ámbito ``` feat(lang): added polish language ``` ### Mensaje de commit para una corrección usando un número de problema (opcional) ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Introducción En el desarrollo de software, ha sido mi experiencia que los errores en el código son introducidos con más frecuencia en las fronteras de la aplicación. Los tests unitarios funcionan muy bien para probar las interacciones que el mantenedor conoce, pero hacen un mal trabajo capturando la manera interesante, a veces inesperada, en que una comunidad usa una librería. Cualquiera que haya actualizado una versión corregida de una dependencia para luego darse cuenta de que la aplicación empieza a arrojar un flujo de 500 errores, sabe lo importante que es un historial de commits legible (e [idealmente un bien mantenido CHANGELOG](http://keepachangelog.com/en/0.3.0/)) para el consiguiente proceso forense. La especificación de Commits Convencionales propone introducir una convención estandarizada y ligera sobre los mensajes de los commits. Esta convención encaja con [SemVer](http://semver.org), pidiéndole a los desarrolladores de software describir en los mensajes de los commits, las características, correcciones y cambios que rompen el uso de la API que hagan. Al introducir esta convención, creamos un lenguaje común que permite depurar más fácilmente los problemas a través de las fronteras de un proyecto. ## Especificación Las palabras “DEBE” (“MUST”), “NO DEBE” (“MUST NOT”), “REQUIERE” (“REQUIRED”), “DEBERÁ” (“SHALL”), “NO DEBERÁ” (“SHALL NOT”), “DEBERÍA” (“SHOULD”), “NO DEBERÍA” (“SHOULD NOT”), “RECOMIENDA” (“RECOMMENDED”), “PUEDE” (“MAY”) Y “OPCIONAL” (“OPTIONAL”) en este documento se deben interpretar como se describe en [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Los commits DEBEN iniciarse con un tipo que consiste en un sustantivo `feat`, `fix`, etc., seguido de dos puntos y un espacio. 1. El tipo `feat` DEBE ser usado cuando un commit agrega una nueva característica a la aplicación o librería. 1. El tipo `fix` DEBE ser usado cuando el commit representa una corrección a un error en el código de la aplicación. 1. Se PUEDE añadir un ámbito opcional después del tipo. El ámbito es una frase que describe una sección de la base del código encerrada en paréntesis, e.g., `fix(parser):` 1. Una descripción DEBE ir inmediatamente después del tipo/ámbito inicial y es una descripción corta de los cambios realizados en el código, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. Un cuerpo del commit más extenso PUEDE agregarse después de la descripción, dando información contextual adicional acerca de los cambios en el código. El cuerpo DEBE iniciar con una línea en blanco después de la descripción. 1. Una nota de pie PUEDE agregarse tras una línea en blanco después del cuerpo o después de la descripción en caso de que no se haya dado un cuerpo. La nota de pie DEBE contener referencias adicionales a los números de problemas registrados sobre el cambio del código (como el número de problema que corrige, e.g.,`Fixes #13`). 1. Los cambios que rompen la API DEBEN ser indicados al inicio de la nota de pie o el cuerpo del commit. Un cambio que rompe la API DEBE contener el texto en mayúsculas `BREAKING CHANGE`, seguido de dos puntos y espacio. 1. Una descripción se DEBE proveer después de `BREAKING CHANGE:`, describiendo qué ha cambiado en la API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. La nota de pie DEBE contener solamente el texto `BREAKING CHANGE`, vínculos externos, referencias a problemas u otra metainformación. 1. Otros tipos distintos a `feat` y `fix` PUEDEN ser usados en los mensajes de los commits. ## ¿Por qué usar Commits Convencionales? * Generación automática de CHANGELOGs. * Determinación automática de los cambios de versión (basado en los tipos de commits). * Comunicar la naturaleza de los cambios a los demás integrantes del equipo, el público o cualquier otro interesado. * Ejecutar procesos de ejecución y publicación. * Hacer más fácil a otras personas contribuir al proyecto, permitiendo explorar una historia de los commits más estructurada. ## FAQ ### ¿Cómo puedo trabajar con los mensajes de los commits en la etapa inicial de desarrollo? Recomendamos trabajar como si ya hubiera lanzado su producto. Típicamente _alguien_, incluso si son sus compañeros desarrolladores, están usando su producto. Ellos querrán saber qué se ha arreglado, qué se ha dañado, etc. ### ¿Qué debo hacer si un commit encaja en más de un tipo de commit? Regrese y haga múltiples commits de ser posible. Parte de los beneficios de los Commits Convencionales es la habilidad para hacer commits más organizados y así mismo PRs. ### ¿No desalienta esto el desarrollo y la iteración rápida? Desalienta moverse rápido de una forma desorganizada. Ayuda a moverse rápido a largo plazo a través de proyectos con una gran variedad de contribuidores. ### ¿Pueden los Commits Convencionales llevar a los desarrolladores a limitar el tipo de commits que hacen ya que estarán pensando en los tipos previstos? Los Commits Convencionales nos animan a hacer más de cierto tipo de commits como _fixes_. Adicionalmente, la flexibilidad de los Commits Convencionales permite a su equipo generar sus propios tipos y cambiarlos a lo largo del tiempo. ### ¿Cómo se relaciona esto con SemVer? El tipo de commit `fix` se traduce a un cambio de versión `PATCH`. El tipo de commit `feat` se traduce a un cambio de versión `MINOR`. Commits con el texto `BREAKING CHANGE`, sin importar su tipo, se traducen a un cambio de versión `MAJOR`. ### ¿Cómo puedo versionar mis extensiones a la especificación de Commits Convencionales, e.g. `@jameswomack/conventional-commit-spec`? Recomendamos usar SemVer para liberar su propia extensión a esta especificación (¡y lo animamos a hacer esta extensión!) ### ¿Qué debo hacer si por accidente uso un tipo de commit equivocado? #### Cuando utiliza un tipo que es de la especificación pero no es el correcto, e.g. `fix` en lugar de `feat` Antes de combinar o liberar el error, recomendamos usar `git rebase -i` para editar el historial de los commits. Después de que se ha liberado, la limpieza será distinta de acuerdo con las herramientas y procesos que usted use. #### Cuando se usa un tipo que no está en la especificación, e.g. `feet` instead of `feat` En el peor de los escenarios, no es el fin del mundo si aparece un commit que no cumple con las especificaciones de los commits convencionales. Simplemente, el commit será ignorado por las herramientas que se basen en esta especificación. ### ¿Deben todos los que contribuyen a mi proyecto usar esta especificación? ¡No! Si usa un flujo de trabajo basado en `squash` los líderes del proyecto pueden limpiar el mensaje en el momento en que se incorpora, sin agregar cargas adicionales a quienes contribuyen casualmente. Un flujo de trabajo común para esto es configurar su sistema de git para que haga el `squash` de manera automática de un pull request y presente al líder del proyecto un formulario para que ingrese el mensaje de commit correcto al momento de hacer el merge. ================================================ FILE: content/v1.0.0-beta.2/index.fr.md ================================================ --- draft: false aliases: ["/fr/"] --- # Conventional Commits 1.0.0-beta.2 ## Résumé En tant que responsable open-source, il faut rédiger un commit standardisé pour chaque fonctionnalité envoyé sur `master`. Le message du commit doit être structuré comme suit: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
Le commit contient les éléments structurels suivants, permettant de communiquer à l’intention des consommateurs de votre bibliothèque: 1. **fix:** un commit de _type_ `fix` corrige un bogue dans le code (cela est en corrélation avec [`PATCH`](http://semver.org/#summary) en versioning sémantique). 1. **feat:** un commit de _type_ `feat` introduit une nouvelle fonctionnalité dans le code (cela est en corrélation avec [`MINOR`](http://semver.org/#summary) en versioning sémantique). 1. **BREAKING CHANGE:** un commit qui a le texte `BREAKING CHANGE:` qui est facultatif au début du texte ou section de pied de page introduit un changement cassant l'API (cela est en corrélation avec [`MAJOR`](http://semver.org/#summary) en versioning sémantique). Un changement radical peut faire partie des commits de _type_. par exemple, `fix:`, `feat:` & `chore:` qui sont tous valables, même additionnés les un avec les autres _type_. 1. Others: commit de _types_ autre que `fix:` et `feat:` sont autorisés, par exemple [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (basé sur [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommande `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, et d'autres. Nous recommandons également `improvement` pour les commits qui améliorent une implémentation en cours sans ajouter de nouvelle fonctionnalité ou correction de bogue. Remarquez que ces types ne sont pas prescrits par la spécification de Conventional Commits et n'ont aucun effet implicite dans la gestion des versions sémantiques (à moins qu'ils ne comportent une rupture, qui n'est PAS recommandée).
Un scope peut être fournie au type d'un commit, pour fournir des informations contextuelles supplémentaires et le contenu entre parenthèses, par exemple, `feat (analyseur): ajoute la possibilité d'analyser' des tableaux`. ## Exemples ### Message de commit avec description et changement radical dans le texte ``` feat: permet à l'objet de configuration fourni d'étendre d'autres configurations BREAKING CHANGE: la clé `extends` dans le fichier de configuration est maintenant utilisée pour étendre d'autres fichiers de configuration ``` ### Message commit sans corps de texte ``` docs: correction d'orthographe dans CHANGELOG ``` ### Message commit avec scope ``` feat(lang): ajout de la langue polonaise ``` ### Message commit pour un correctif à l'aide d'un numéro d'un issue (facultatif). ``` fix: fautes de frappe mineures dans le code voir le problème pour plus de détails sur les fautes de frappe corrigées fixes issue #12 ``` ## Introduction D'après mon expérience, les bogues sont le plus souvent introduits en développement logiciel aux limites entre les applications. Les tests unitaires sont parfaits pour tester les interactions qu'un responsable open-source connaît, mais faire du mauvais travail de capture sur ces derniers, est souvent inattendues, qu'une communauté utilise une bibliothèque. Toute personne qui a mis à niveau une nouvelle version du correctif d’une dépendance d'application commence à jeter un flux constant d'erreurs 500, sait à quel point un historique de commit lisible (et [idéalement un CHANGELOG bien entretenu](http://keepachangelog.com/en/0.3.0/)) est un processus adéquat qui s'ensuit. La spécification de Conventional Commits propose d’introduire un poids léger et normalisé les messages des commits. Cette convention s’articule avec [SemVer](http://semver.org), demandez aux développeurs de logiciels de décrire dans les messages de commit, les fonctionnalités, les correctifs et les ruptures les changements qu'ils font. En introduisant cette convention, nous créons un langage commun qui facilite le débogage des problèmes au-delà des limites du projet. ## Spécification Les mots clés ”DOIT” (“MUST”), “NE DOIT PAS” (“MUST NOT”), “REQUIS” (“REQUIRED”), “NE DOIT” (“SHALL”), “NE DOIT PAS” (“SHALL NOT”), “NE DEVRAIT” (“SHOULD”), “NE DEVRAIT PAS” (“SHOULD NOT”), “RECOMMANDÉ” (“RECOMMENDED”), “PEUT” (“MAY”), et “FACULTATIF” (“OPTIONAL”) dans ce document doivent être interprétés comme décrit dans [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Les commits DOIT être préfixés par un type, qui consiste en un nom, `feat`,` fix`, etc., suivi d'un côlon et d'un espace. 1. Le type `feat` DOIT être utilisé lorsqu'un commit ajoute une nouvelle fonctionnalité à votre application. ou bibliothèque. 1. Le type `fix` DOIT être utilisé lorsqu'un commit représente un correctif pour votre application. 1. Un scope facultative PEUT être fournie après un type. Un scope est une phrase décrivant une section du code encadrée par des parenthèses, par exemple, `fix (analyseur)):` 1. Une description DOIT suivre immédiatement le préfixe type/scope. La description est une brève description des modifications du code, par exemple, _fix: problème d'analyse d'un tableau lorsque plusieurs espaces étaient contenus dans string._ 1. Un texte plus long PEUT être fourni après la description courte, fournissant des informations contextuelles supplémentaires sur les modifications du code. Le texte DOIT commencer par une ligne vide après la description. 1. Un pied de page PEUT être fourni une ligne vierge après le texte (ou après la description si le texte manque). Le pied de page DEVRAIT contenir des références de problèmes supplémentaires concernant les modifications du code (telles que les problèmes qu’il corrige, par exemple, `Fixes #13`). 1. Les changements de rupture DOIVENT être indiqués au tout début du pied de page ou de la section du corps de texte d'un commit. Un changement radical DOIT être dans le texte en majuscule `BREAKING CHANGE`, suivi de deux points et d'un espace. 1. Une description DOIT être fournie après le «BREAKING CHANGE:», décrivant la modification de l’API, par exemple, _BREAKING CHANGE: les variables d’environnement sont désormais prioritaires sur les fichiers de configuration._ 1. Le pied de page NE DOIT contenir que «BREAKING CHANGE», des liens externes, des références de publication et d'autres méta-informations. 1. Des types autres que `feat` et` fix` PEUVENT être utilisés dans vos messages de commit. ## Pourquoi Utiliser Conventional Commits * Génération automatique de CHANGELOGs. * Déterminer automatiquement un choc de version sémantique (en fonction des types de commits débarqués). * Communiquer la nature des changements aux coéquipiers, au public et aux autres parties prenantes. * Déclencher des processus de construction et de publication. * Faciliter la contribution des personnes à vos projets en leur permettant d’explorer un historique de commit plus structurée. ## FAQ ### Comment dois-je gérer les messages de commit dans la phase de développement initiale ? Nous vous recommandons de procéder comme si vous aviez déjà publié un produit. Généralement *quelqu'un*, même si ce sont vos collègues développeurs de logiciels, utilise votre logiciel. Ils voudront savoir ce qui est corrigé, ce qui casse, etc. ### Que dois-je faire si le commit est conforme à plusieurs types ? Revenez en arrière et faites plusieurs commits autant que possible. Une partie des avantages de Conventional Commits réside dans sa capacité à nous amener à créer des commits et des relations publiques plus organisés. ### Est-ce que cela ne décourage pas le développement rapide et l’itération rapide ? Cela décourage les commits rapides de manière désorganisée. Il vous aide à être en mesure que vous commité rapidement à long terme dans plusieurs projets avec des contributeurs variés. ### Les engagements conventionnels peuvent-ils amener les développeurs à limiter le type d’engagements qu’ils font car ils penseront aux types fournis? Conventional Commits nous encouragent à utiliser davantage certains types de commits tels que les correctifs. En dehors de cela, la flexibilité de Conventional Commits permet à votre équipe de créer ses propres types et de les modifier au fil du temps. ### Quel est le lien avec SemVer ? Les corrections de type `fix` devraient être traduites en` PATCH`. Les commits de type `feat` devraient être traduits en versions` MINOR`. Les commits avec `BREAKING CHANGE` dans les commits, quel que soit leur type, doivent être traduits en versions` MAJOR`. ### Comment dois-je mettre à jour mes extensions de la spécification de Conventional Commits, par exemple `@jameswomack/conventionnel-commit-spec` ? Nous vous recommandons d’utiliser SemVer pour publier vos propres extensions à cette spécification (et vous encourage à faire ces extensions!) ### Que dois-je faire si j'utilise accidentellement le type de commit incorrect ? #### Lorsque vous utilisez un type de commit incorrect, par exemple `fix` au lieu de` feat` Avant de fusionner ou de relâcher l'erreur, nous vous recommandons d'utiliser `git rebase -i` pour éditer l'historique des commits. Après la publication, le nettoyage sera différent selon les outils et les processus que vous utilisez. #### Lorsque vous utilisez un type qui n'est *pas* dans les spécifications, par exemple `pieds` au lieu de` feat` Dans le pire des cas, ce n'est pas la fin du monde si un commit atterrit sans respecter les spécifications de Conventional Commits. Cela signifie simplement que l’engagement sera raté par des outils basés sur les spécifications. ### Est-ce que tous mes contributeurs doivent utiliser les spécifications de Conventional Commits ? Non! Si vous utilisez un flux de travail basé sur squash sur Git, les responsables principaux peuvent nettoyer les messages des commits au fur et à mesure de leur fusion, ce qui permet de ne pas ajouter de charge de travail aux committers occasionnels. Un processus courant consiste à ce que votre système git écrase automatiquement les commits d'une demande d'extraction et présente un formulaire permettant au responsable de la maintenance d'entrer le message du commit git approprié pour la fusion. ================================================ FILE: content/v1.0.0-beta.2/index.it.md ================================================ --- draft: false aliases: ["/it/"] --- # Commit Convenzionali 1.0.0-beta.2 ## Riepilogo Da maintainer di codice open source, devo poter scrivere messaggi standardizzati per i commit ed eseguire lo squash dei feature branch nel `master`. I messaggi dei commit dovrebbero seguire la seguente struttura: --- ``` [contesto opzionale]: [corpo opzionale] [piè di pagina opzionale] ``` ---
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicare l'intento al consumatore della libreria: 1. **fix:** un commit di _tipo_ `fix` risolve un errore nel codice (correlato al [`PATCH`](http://semver.org/#summary) in un versionamento semver). 1. **feat:** un commit di _tipo_ `feat` introduce una nuova funzionalità al codice (correlato al [`MINOR`](http://semver.org/#summary) in un versionamento semver). 1. **BREAKING CHANGE:** un commit che contiene il testo `BREAKING CHANGE:` all'inizio delle sezioni opzionali _corpo_ o _piè di pagina_, introduce una breaking API change (correlato al [`MAJOR`](http://semver.org/#summary) in un versionamento semver). Una _breaking change_ può essere parte di un commit di qualsiasi _tipo_. Es: I tipi `fix:`, `feat:` & `chore:` sono tutti validi, cosí come qualsiasi altro _tipo_. 1. Extra: sono ammessi ulteriori _tipi_ oltre `fix:` e`feat:`, per esempio [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (che si basa sulla [convenzione Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) raccomanda `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, ed altri. Noi raccomandiamo anche `improvement` per commit che migliorano un'implementazione esistente senza aggiungere nuove funzionalità o risolvere un errore. Notare che questi _tipi_ non sono mantenuti da questa specifica, e non hanno un effetto sul versionamento semver (a meno che non introducano una _BREAKING CHANGE_, il quale NON è raccomandato).
Un _contesto_ potrebbe essere aggiunto al _tipo_ di commit, al fine di offrire ulteriori informazioni contestuali. Da aggiungere tra delle parentesi tonde, Es: `feat(parser): add ability to parse arrays`. ## Esempi ### Messaggio di un commit con una _descrizione_ e una breaking change nel _corpo_ ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Messaggio di un commit senza una _descrizione_ ``` docs: correct spelling of CHANGELOG ``` ### Messaggio di un commit con uno _contesto_ ``` feat(lang): added polish language ``` ### Messaggio di un commit per un `fix` utilizzando il numero della issue (opzionale) ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Introduzione Nello sviluppo software, secondo la mia esperienza, gli errori sono spesso introdotti ai limiti tra le applicazioni. I test unitari vanno benissimo per le interazioni che i mantenitori open source conoscono, ma non fanno un ottimo lavoro nel catturare tutti i modi interessanti, spesso inaspettati, con i quali la comunità utilizza una libreria. Solamente chi ha visto la propria applicazione restituire errori 500 dopo aver aggiornato una dipendenza ad una nuova versione patch, sa quanto sia importante una cronologia di commit facilmente leggibile (e nel migliore dei casi [un CHANGELOG ben mantenuto](http://keepachangelog.com/en/0.3.0/)) per il processo di investigazione che dovrà affrontare. La specifica per commit convenzionali propone l'introduzione di una convenzione facilmente applicabile ai messaggi dei commit. Questa convenzione legata al [SemVer](http://semver.org), chiede ai sviluppatori software di descrivere nei messaggi dei commit qualsiasi feature, fix e breaking change loro abbiano fatto. Introducendo questa convenzione, si crea un linguaggio comune che rende più semplice rimuovere errori tra progetti. ## Specifica Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DEVE iniziare con un _tipo_, il quale consiste in un sostantivo, `feat`, `fix`, etc., seguito dai due punti ed uno spazio. 1. Il _tipo_ `feat` DEVE essere usato quando un commit aggiunge una funzionalità all'applicazione o libreria. 1. Il _tipo_ `fix` DEVE essere usato quando un commit corregge un errore all'applicazione o libreria. 1. Un _contesto_ opzionale POTREBBE essere fornito dopo il _tipo_. Un _contesto_ rappresenta una sezione dell'applicazione o della libreria, il contenuto va racchiuso tra parentesi. Es: `fix(parser):` 1. Una _descrizione_ DEVE seguire immediatamente il _tipo_ (con eventuale _contesto_). Per _descrizione_ si intende una breve spiegazione riguardo la modifica al codice. Es: _fix: array parsing issue when multiple spaces were contained in string._ 1. Un _corpo_ del commit più lungo POTREBBE essere aggiunto dopo una breve _descrizione_, aggiungendo ulteriori informazioni contestuali riguardo le modifiche apportate al codice. Il _corpo_ DEVE iniziare dopo una linea vuota dalla _descrizione_. 1. Un _piè di pagina_ POTREBBE essere aggiunto inserendo una linea vuota dopo il _corpo_. Il _piè di pagina_ DOVREBBE contenere ulteriori informazioni riguardo le modifiche apportate al codice (come le issue che risolve, Es: `fixes #13, #5`). 1. Una _breaking changes_ DEVE essere indicata all'inizio delle sezioni _piè di pagina_ o del _corpo_ del commit. Una _breaking change_ DEVE essere scritta in maiuscolo `BREAKING CHANGE`, seguita dai due punti ed uno spazio. 1. Una descrizione DEVE essere aggiunta dopo il testo `BREAKING CHANGE: `, descrivendo il cambiamento delle API. Es: _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Il _piè di pagina_ DEVE solo contenere `BREAKING CHANGE`, collegamenti esterni, riferimenti alle issueed ulteriori meta-informazioni. 1. Un commit POTREBBE utilizzare altri _tipi_ al di fuori di `feat` e `fix` nel messaggio. ## Perchè utilizzare commit convenzionali * CHANGELOG generati automaticamente. * Determina automaticamente l'incremento di un versionamento semver (basandosi sui tipi di commit utilizzati). * Comunica la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate. * Attiva build e processi di rilascio. * Rendi più semplice alle persone contribuire al tuo progetto, dando la possibilità di esplorare una cronologia di commit più strutturata. ## FAQ ### Come dovrei comportarmi con i messaggi dei commit nella fase iniziale del progetto? Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente *qualcuno*, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc. ### Cosa faccio se il tipo di commit è conforme a più di un tipo? Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request organizzate meglio. ### Non scoraggia sviluppo ed iterazioni rapidi? Scoraggia a farlo in una maniere disorganizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori. ### Potrebbe Commit Convenzionali limitare gli sviluppatori a fare solamente alcuni tipi commit perchè penseranno nei tipi forniti dalla specifica? Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo. ### Come si collega a SemVer? I commit di tipo `fix` dovrebbero essere traducibili ai rilasci `PATCH`. I commit di tipo `feat` dovrebbero essere traducibili ai rilasci `MINOR`. I commit con `BREAKING CHANGE`, indipendentemente dal tipo, dovrebbero essere traducibili ai rilasci `MAJOR`. ### Come dovrei versionare le mie estensioni per la specifica Commit Convenzionali? (Es: `@jameswomack/conventional-commit-spec`) Raccomandiamo l'utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!) ### Cosa faccio se accidentalmente utilizzo un tipo di commit sbagliato? #### Quando usi un tipo della specifica ma non quello giusto (Es: `fix` invece di `feat`) Se ancora devi creare il merge o il rilascio dell'errore, raccomandiamo l'utilizzo di `git rebase -i` per riscrivere la cronologia dei commit. Nel caso ti abbia già rilasciato questa correzione dipende dai tool e processi che usi. #### Quando usi un tipo *non* della specifica (Es: `feet` invece di `feat`) Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica. ### Devono tutti i contributori seguire la specifica Commit Convenzionali? No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato. ================================================ FILE: content/v1.0.0-beta.2/index.md ================================================ --- draft: false --- # Conventional Commits 1.0.0-beta.2 ## Summary As an open-source maintainer, squash feature branches onto `master` and write a standardized commit message while doing so. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in semantic versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning). 1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning). A breaking change can be part of commits of any _type_. e.g., a `fix:`, `feat:` & `chore:` types would all be valid, in addition to any other _type_. 1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. We also recommend `improvement` for commits that improve a current implementation without adding a new feature or fixing a bug. Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE, which is NOT recommended).
A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`. ## Examples ### Commit message with description and breaking change in body ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit message with no body ``` docs: correct spelling of CHANGELOG ``` ### Commit message with scope ``` feat(lang): added polish language ``` ### Commit message for a fix using an (optional) issue number. ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Introduction In software development, it's been my experience that bugs are most often introduced at the boundaries between applications. Unit testing works great for testing the interactions that an open-source maintainer knows about, but do a poor job of capturing all the interesting, often unexpected, ways that a community puts a library to use. Anyone who has upgraded to a new patch version of a dependency, only to watch their application start throwing a steady stream of 500 errors, knows how important a readable commit history (and [ideally a well maintained CHANGELOG](http://keepachangelog.com/en/0.3.0/)) is to the ensuing forensic process. The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with [SemVer](http://semver.org), asking software developers to describe in commit messages, features, fixes, and breaking changes that they make. By introducing this convention, we create a common language that makes it easier to debug issues across project boundaries. ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by a colon and a space. 1. The type `feat` MUST be used when a commit adds a new feature to your application or library. 1. The type `fix` MUST be used when a commit represents a bug fix for your application. 1. An optional scope MAY be provided after a type. A scope is a phrase describing a section of the codebase enclosed in parenthesis, e.g., `fix(parser):` 1. A description MUST immediately follow the type/scope prefix. The description is a short description of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. 1. A footer MAY be provided one blank line after the body (or after the description if body is missing). The footer SHOULD contain additional issue references about the code changes (such as the issues it fixes, e.g.,`Fixes #13`). 1. Breaking changes MUST be indicated at the very beginning of the footer or body section of a commit. A breaking change MUST consist of the uppercase text `BREAKING CHANGE`, followed by a colon and a space. 1. A description MUST be provided after the `BREAKING CHANGE: `, describing what has changed about the API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. The footer MUST only contain `BREAKING CHANGE`, external links, issue references, and other meta-information. 1. Types other than `feat` and `fix` MAY be used in your commit messages. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've an already released product. Typically *somebody*, even if its your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### What do I do if the commit conforms to more than one of the commit types? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the conventional commit specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the conventional commit specification? No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ================================================ FILE: content/v1.0.0-beta.2/index.pl.md ================================================ --- draft: false aliases: ["/pl/"] --- # Konwencjonalne Commity 1.0.0-beta.2 ## Streszczenie Jako opiekun otwartych źródeł, spłaszczaj (squashuj) gałęzie funkcyjne (featurowe) do gałęzi głównej - `master` oraz pisz ustandaryzowane opisy dostarczeń (commitów). Opis dostarczenia powinien wyglądać następująco: --- ``` [opcjonalny zakres]: [opcjonalne ciało wiadomości] [opcjonalna stopka wiadomości] ``` ---
Wiadomość zawiera następujące strukturalne elementy po to, aby zakomunikować intencje do użytkowników Twojej biblioteki: 1. **fix:** dostarczenie _typu_ `fix` naprawia błąd obecny w Twoim kodzie (powiązane z [`PATCH`](http://semver.org/#summary) w wersjonowaniu semantycznym). 1. **feat:** dostarczenie _typu_ `feat` wprowadza nowe funkcje do Twojej biblioteki (powiązane z [`MINOR`](http://semver.org/#summary) w wersjonowaniu semantycznym). 1. **BREAKING CHANGE:** dostarczenie, które posiada tekst `BREAKING CHANGE:` na początku jego opcjonalnego ciała bądź stopki wprowadza zmianę łamiącą kompatybilność API (powiązane z [`MAJOR`](http://semver.org/#summary) w wersjonowaniu semantycznym). Zmiana łamiąca kompatybilność wsteczną może być elementem zmian każdego innego _typu_, np. `fix:`, `feat:` & `chore:` - wszystkie byłyby poprawne, w dodatku do każdego innego _typu_. 1. Inne: commity _typu_ innego niż `fix:` oraz `feat:` są dozwolone, np. [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (bazowano na [konwencji Angulara](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) poleca `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, oraz inne. My polecamy także `improvement` dla dostarczeń, które ulepszają obecną implementację bez dodawania nowych funkcjonalności lub naprawy błędów. Zauważ, że te typy nie są obowiązkowe według specyfikacji konwencjonalnych commitów i nie mają wpływu na wersjonowanie (chyba, że zawierają BREAKING CHANGE, co NIE JEST rekomendowane).
Przy typie dostarczenia może zostać podany zakres w celu dostarczenia dokładniejszej informacji o kontekście dostarczenia. Zawiera się on w nawiasach następujących bezpośrednio po typie, np. `feat(parser): dodano możliwość parsowania list`. ## Przykłady ### Commit z opisem oraz zmianą niekomatybilną wstecz (BREAKING CHANGE) ``` feat: pozwól dostarczonemu obiektowi konfiguracyjnemu na rozszerzanie innych konfiguracji BREAKING CHANGE: klucz `extends` w pliku konfiguracyjnym jest teraz używany do rozszerzania innych konfiguracji ``` ### Commit bez ciała wiadomości ``` docs: poprawniono pisownię w CHANGELOG ``` ### Commit z określonym zakresem ``` feat(lang): dodano język polski ``` ### Commit dostarczenia naprawiającego buga określonego w raporcie błędu (issue) o (opcjonalnym) numerze ``` fix: kilka literówek w kodzie po więcej szczegółów udaj się do raportu błędu fixes issue #12 ``` ## Wprowadzenie Podczas rozwoju oprogramowania zauważyłem, że błędy często występują na granicy pomiędzy aplikacjami. Testy jednostkowe doskonale zdają egzamin w przypadkach, o których opiekun biblioteki pomyślał, jednak sposoby, w jakich oprogramowanie zostanie użyte przez społeczność często, choć interesujące mogą być nie do pomyślenia. Tutaj testy jednostkowe niezbyt zdają egzamin. Każdy, kto kiedykolwiek zaktualizował zależność swojej aplikacji, chociażby o jedną wersję _patch_, tylko po to, aby zobaczyć, jak jego aplikacja zaczyna rzucać 500 błędami, wie, jak ważną rolę stanowi czytelna historia dostarczeń (oraz dodatkowo [dobrze zarządzany DZIENNIK ZMIAN (CHANGELOG)](http://keepachangelog.com/en/0.3.0/)) podczas naprawy. Specyfikacja Konwencjonalnych Commitów proponuje wprowadzenie ustandaryzowanej, lekkiej konwencji wykorzystującej wiadomości w dostarczeniach. Konwencja ta łączy się z [SemVer](http://semver.org), nakazując deweloperom opisywanie w wiadomościach podczas dostarczania jakie funkcje wprowadzają, co naprawiają oraz jakie niekompatybilne wstecz zmiany wnoszą. Wprowadzając tę konwencję, tworzymy powszechny język, który pozwala na dużo łatwiejsze wyłapywanie błędów występujących na granicy projektu z jego zależnościami. ## Specyfikacja Następujące terminy “MUSI” (“MUST”), “NIE MOŻE” (“MUST NOT”), “WYMAGANY” (“REQUIRED”), “MA BYĆ” (“SHALL”), “NIE BĘDZIE” (“SHALL NOT”), “POWINIEN” (“SHOULD”), “NIE POWINIEN” (“SHOULD NOT”), “ZALECANY” (“RECOMMENDED”), “MOŻE” (“MAY”) oraz “OPCJONALNY” (“OPTIONAL”) pojawiające się w tym dokumencie rozumiane są zgodnie z ich opisem na stronie: [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Dostarczenie MUSI być poprzedzone typem, który składa się z rzeczownika, np. `feat`, `fix`, itp., oraz następującymi bezpośrednio po nim dwukropka oraz spacji. 1. Typ `feat` MUSI być użyty, gdy dostarczenie dodaje nową funkcję do Twojej aplikacji bądź biblioteki. 1. Typ `fix` MUSI być użyty, kiedy dostarczenie naprawia błąd w Twojej aplikacji. 1. Opcjonalny zakres MOŻE być podany po typie. Zakres jest to fraza opisująca obszar kodu zawarta w nawiasach okrągłych, np., `fix(parser):` 1. Opis MUSI występować zaraz po przedrostku typu/zakresu. Opis jest to krótka notka stanowiąca o treści dostarczenia, np., _fix: problem podczas parsowania listy, kiedy string zawierał wiele spacji._ 1. Dłuższe ciało wiadomości MOŻE być podane po krótkim opisie. Ciało MUSI zaczynać się jedną pustą linię po opisie. 1. Stopka MOŻE być podane jedną linię za ciałem wiadomości. Stopka POWINNA zawierać dodatkowe informacje odnośnie zgłoszeń błędów lub propozycji funkcjonalności, które rozwiązuje, np. `fixes #13, #5`. 1. Zmiany niekompatybilne wstecz MUSZĄ być zaznaczone na samym początku sekcji ciała wiadomości lub stopki. Informacja o niekompatybilności MUSI zawierać tekst `BREAKING CHANGE`, wraz z następującymi po nim dwukropkiem oraz spacją. 1. Po tekście `BREAKING CHANGE: ` MUSI następować opis mówiący o tym, co zostało zmienione w kodzie w sposób, który niszczy kompatybilność wstecz, np. _BREAKING CHANGE: zmienne środowiskowe mają teraz większy priorytet niż pliki konfiguracyjne._ 1. Stopka powinna zawierać tylko i wyłącznie `BREAKING CHANGE`, linki zewnętrzne, odnośniki do raportów błędów oraz inne meta-informacje. 1. Typy inne niż `feat` oraz `fix` MOGĄ być użyte w wiadomościach Twoich dostarczeń. ## Dlaczego używać Konwencjonalnych Commitów * Automatycznie generowany DZIENNIK ZMIAN. * Automatycznie wykrywana zmiana semantycznej zmiany wersji (określana na podstawie typów dostarczonych zmian) * Komunikowanie zmian członkom zespołu, publice, oraz innym zainteresowanym. * Wyzwalanie procesów budowania oraz publikacji. * Łatwiejsze włączenie się w rozwój kodu przez ludzi z zewnątrz poprzez pozwolenie im na przeglądanie bardziej zorganizowanej historii dostarczeń. ## FAQ ### Jak powinienem radzić sobie z wiadomościami dostarczeń w fazie początkowej rozwoju kodu? Polecamy, żebyś postępował tak, jakby Twój produkt już został wydany. Zazwyczaj *ktoś*, nawet jeśli jest to Twój kolega z zespołu, już używa Twojego oprogramowania. Będzie chciał wiedzieć, co zostało naprawione, co nie działa itp. ### Co powinienem zrobić, jeśli dostarczenie pasuje do więcej niż jednego typu? Wróć się i stwórz więcej dostarczeń, jeśli to tylko możliwe. Częściową korzyścią z Konwencjonalnych Commitów jest zdolność do tworzenia kodu w bardziej zorganizowany sposób. ### Czy takie podejście nie zniechęca do szybkiego rozwoju oraz szybkich iteracji? Zniechęca do szybkiego poruszania się do przodu w niezorganizowany sposób. Pozwala Ci na szybkie posuwanie się do przodu w wielu projektach oraz różnorodnych deweloperów. ### Czy Konwencjonalne Commity mogą prowadzić do zmniejszenia ilości typów dostarczanych przez deweloperów, ponieważ będą myśleć w przestrzeni wymienionych typów? Konwencjonalne Commity zachęcają do tworzenia większej ilości dostarczeń danego typu, np. napraw. Z innego punktu widzenia, elastyczność Konwencjonalnych Commitów pozwala Twojemu zespołowi stworzyć własne typy oraz zmieniać je z biegiem czasu. ### Jak jest to powiązane z SemVer? Wiadomości typu `fix` powinny być traktowane tak jak `PATCH`. Wiadomości typu `feat` tak jak `MINOR`, natomiast dostarczenia zawierające `BREAKING CHANGE`, bez względu na typ, powinny być traktowane jak `MAJOR`. ### Jak powinienem wersjonować moje rozszerzenia zgodnie ze specyfikacją Konwencjonalnych Commitów, np. `@jameswomack/conventional-commit-spec`? Zalecamy używanie SemVer do wydawania własnych rozszerzeń do tej specyfikacji (oraz zachęcamy do tworzenia tych rozszerzeń!). ### Co powinienem zrobić, jeśli przypadkowo użyje błędnego typu dostarczenia? #### Jeśli użyłeś typu, który znajduje się w specyfikacji, ale nie jest poprawny, np. `fix` zamiast `feat` Przed dostarczeniem i wydaniem pomyłki, polecamy użyć `git rebase -i` w celu zmienienia historii dostarczeń. Zmiana po dostarczeniu zależy od narzędzi oraz procesów, których używasz. #### Jeśli użyłeś typu, który *nie* znajduje się w specyfikacji, np. `feet` zamiast `feat` W najgorszym przypadku - to nie koniec świata, jeśli dostarczenie niespełniające specyfikacji Konwencjonalnych Commitów zostanie wprowadzone. Po prostu znaczy to, że będzie pominięty przez narzędzia bazujące na specyfikacji. ### Czy wszyscy moi kontrybutorzy muszą używać specyfikacji Konwencjonalnych Commitów? Nie! Jeśli używasz trybu bazującego na spłaszczaniu historii dostarczeń, wtedy główni opiekunowie projektu mogą posprzątać wiadomości podczas dostarczania. Takie podejście nie narzuca żadnego obowiązku na osoby dostarczające od czasu do czasu. Powszechnym podejściem jest używanie automatycznego spłaszczania historii dostarczeń z prośby wciągnięcia (pull request) oraz wyświetlenie formularza osobie dostarczającej w celu wypełnienia wiadomości poprawną treścią. ================================================ FILE: content/v1.0.0-beta.2/index.ru.md ================================================ --- draft: false aliases: ["/ru/"] --- # Общепринятые Коммиты 1.0.0-beta.2 ## Главное Как разработчики приложений с открытым исходным кодом, использующие слияние (squash) git'а в ветку `master` должны писать общепринятые сообщения коммитов. Сообщения коммитов должны иметь следующую структуру: --- ``` [optional область]: <краткое описание> [optional тело] [optional подвал] ``` ---
Коммиты включают следующие элементы, чтоб сообщить пользователям вашей библиотеки, что ни в себе содержат: 1. **fix:** - коммит _типа_ `fix`, который исправляет баги в вашем коде (он соотносится с [`PATCH`](http://semver.org/#summary) в правилах семантического управления версиями). 1. **feat:** - коммит _type_ `feat`, который добавляет новую функциональность в ваш код (он соотносится с [`MINOR`](http://semver.org/#summary) в правилах семантического управления версиями). 1. **BREAKING CHANGE:** - коммит, который содержит текст `BREAKING CHANGE:` в начале своего необязательного тела или подвала, и несет в себе описание нарушений обратной совместимости в API (он соотносится с [`MAJOR`](http://semver.org/#summary) в правилах семантического управления версиями). BREAKING CHANGE может быть частью коммита любого _типа_. 1. Другие: коммиты, _отличные_ от `fix:` и `feat:` так же разрешены, например, [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (основанный на [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рекомендует `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` и другие. Мы так же рекомендуем `improvement` для коммитов, которые улучшают текущую реализацию без добавления новой функциональности или исправления ошибок. Обратите внимание, что данный тип коммитов не управляется данной спецификацией и не имеет никакого соотношения в правилах семантического управления версиями (за исключением случае, если он не содержит в себе BREAKING CHANGE).
Область (scope) может быть определена для любого типа коммита, чтоб описать контекст коммита. Она содержится в круглых скобках, например, `feat(parser): add ability to parse arrays`. ## Примеры ### Коммит, добавляющий новую функциональность и содержащий описание нарушения обратной совместимости в теле ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Коммит без тела ``` docs: correct spelling of CHANGELOG ``` ### Коммит с указанной областью (scope) ``` feat(lang): added polish language ``` ### Коммит, исправляющий баги и содержащий (необязательный) номер в баг-трекере (issue) в подвале ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Вступление В разработке программного обеспечения я заметил, что ошибки чаще всего распространяются между приложениями. Модульное тестирование отлично подходит для тестирования взаимодействий, о которых знает разработчик с открытым исходным кодом, но не затрагивает интересов тех, то использует вашу библиотеку. Любой, кто обновился до новой версии патча зависимостей, только для того, чтобы увидеть, как его приложение начинает вываливаться с 500 ошибкой, знает, насколько важна хорошая читаемая история изменений приложения (и [в идеале хорошо сохранившийся CHANGELOG](http://keepachangelog.com/en/0.3.0/)). Общепринятые Коммиты - это простое соглашение для написания сообщений коммитов. Оно определяет простой набор правил для создания точной истории коммитов, а так же упрощает написание автоматических утилит поверх истории коммитов. Данное соглашение совместимо с правилами семантического управления версиями [SemVer](http://semver.org), описывая правила добавления новой функциональности, исправления багов и описания нарушения обратной совместимости в сообщениях коммитов. Внедряя это соглашение, мы создаем общий язык, который упрощает отладку между проектами. ## Спецификация Слова “ДОЛЖЕН”, “ДОЛЖНО”, “ДОЛЖНЫ” (“MUST”, “SHOULD”, “SHALL”), “МОГУТ”, “МОЖЕТ” (“MAY”) и “НЕ ОБЯЗАТЕЛЬНАЯ” (“OPTIONAL”) в этом документе должны интерпретироваться как описано в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Коммиты ДОЛЖНЫ начинаться с префикса, который содержит существительное `feat`, `fix` и др., за которым следует двоеточие и пробел. 1. Тип `feat` ДОЛЖЕН использоваться для коммитов, которые добавляют новую функциональность в ваше приложение или библиотеку. 1. Тип `fix` ДОЛЖЕН использоваться для коммитов, которые исправляют баги в вашем приложении или библиотеки. 1. НЕ ОБЯЗАТЕЛЬНАЯ область (scope) МОЖЕТ быть указана после типа. Область - это фраза, описывающая контекст кодовой базы, измененной коммитом, заключенная в круглые скобки. Например, `fix(parser):`. 1. Краткое описания ДОЛЖНО следовать сразу же после указания префикса типа/области. Краткое описание - это сжатое описание изменения кода, которое несет в себе коммит, например, `fix: array parsing issue when multiple spaces were contained in string.` 1. Тело коммита содержит в себе дополнительное, полное описание о изменении кодовой базы. Оно МОЖЕТ следовать после краткого описания. Тело ДОЛЖНО идти после краткого описания, через одну пустую строку. 1. Подвал МОЖЕТ идти после тела коммита через одну пустую строку. Подвал ДОЛЖЕН содержать дополнительную ссылку на запись в баг-трекере (issue) об изменениях в кодовой базы (т.е. issue, которое он исправляет, например `Fixes #13`). 1. Нарушения обратной совместимости ДОЛЖНЫ содержаться в самом начале тела или подвала коммита. Нарушения обратной совместимости ДОЛЖНЫ начинаться с текста в верхнем регистре `BREAKING CHANGE`, за которым следует двоеточие и пробел. 1. Описание нарушения обратной совместимости ДОЛЖНО следовать сразу же после `BREAKING CHANGE: `. Оно должно разъяснять, что изменилось в API. Например, `BREAKING CHANGE: environment variables now take precedence over config files.` 1. Подвал ДОЛЖЕН содержать только `BREAKING CHANGE`, внешние ссылки, ссылки на номера задач в баг-трекере (issue), и другую мета-информацию. 1. Типы отличные от `feat` и `fix` МОГУТ использоваться в сообщениях коммитов. ## Почему нужно использовать Общепринятые Коммиты * Автоматически создаваемые CHANGELOG'и. * Автоматически определяемая семантическая версия приложения или библиотеки (основываясь на типах коммитов). * Коммуникация о характере изменения между товарищами по команде, общественностью и другими заинтересованными сторонами. * Автоматически срабатываемый процесс сборки и публикации. * Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов. ## FAQ ### Как я должен писать сообщения коммитов на начальной стадии разработки? Мы рекомендуем писать сообщения коммитов так, как будто вы уже выпустили продукт. Как правило, *кто-то*, например, ваши коллеги, уже используют ваш код. И они хотят знать, что исправилось, что изменилось, какие нарушения обратной совместимости появились и т.д. ### В каком регистре я должен писать заголовки коммитов? Любой регистр можно использовать, но лучше во всей истории использовать один стиль. ### Что мне делать, если коммит должен содержать больше одного типа? Вернитесь назад и сделайте несколько коммитов, если это возможно. Часть из преимуществ использования Общепринятых Коммитов - это его способность побуждать делать более организованные коммиты и PR'ы. ### Разве это не препятствует быстрому развитию и быстрой интеграции? Это препятствует быстрому развитию в неорганизованном виде. Это помогает быстро двигаться в нескольких проектах с несколькими участниками. ### Могут ли Общепринятые Коммиты заставить разработчиков ограничивать их типы коммитов, потому что им придется думать об этих типах? Общепринятые Коммиты побуждают делать больше коммитов с определенными типами, такими как `fix`. Кроме того, гибкость Общепринятые Коммиты позволяют вашей команде создавать свои собственные типы и изменять их с течением времени. ### Как она связывается с правилами семантического управления версиями [SemVer](http://semver.org)? `fix` тип коммита должен быть отражен в `PATCH`-релизе. `feat` тип коммита должен быть отражен в `MINOR`-релизе. Коммиты с `BREAKING CHANGE` в теле или подвале, не зависимо от типа, должны быть отражены в `MAJOR`-релизе. ### Как я должен версионировать мои расширения к спецификации Общепринятых Коммитов, например, `@jameswomack/conventional-commit-spec`? Мы рекомендуем использовать [SemVer](http://semver.org) для релизов ваших расширений к этой спецификации (и рекомендуем делать эти расширения!). ### Что мне делать, если я случайно использовал не тот тип коммита? #### Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, `fix` вместо `feat` Перед слиянием или релизом ошибки, мы рекомендуем использовать `git rebase -i` для редактирования истории коммитов. После `release`, исправления будут отличаться в зависимости от того, какие инструменты вы используете. #### Когда вы использовали тип, *не* описанный спецификацией, например, `feet` вместо `feat` Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации. ### Должны ли все мои соавторы использовать спецификацию Conventional Commit? Нет! Если ваш рабочий процесс основа на использовании слияния (squash) Git, сопровождающий проекта может отчистить историю всех предыдущих коммитов при их слияния, не добавляя рабочей нагрузки на случайные коммиты. Обычно, рабочий процесс строится на том, что ваша система Git автоматически объединяет (squash) все предыдущие коммиты пред перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового коммита. ================================================ FILE: content/v1.0.0-beta.2/index.zh-hans.md ================================================ --- draft: false aliases: ["/zh/"] --- # 约定式提交 1.0.0-beta.2 ## 概述 开源维护者在将特性分支合并入 `master` 时，可编写标准化的提交说明。 提交说明的结构如下所示： --- ``` <类型>[可选的作用域]: <描述> [可选的正文] [可选的脚注] ``` ---
提交说明包含了下面的结构化元素，以向类库使用者表明其意图： 1. **fix:** _类型_ 为 `fix` 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 [`PATCH`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 1. **feat:** _类型_ 为 `feat` 的提交表示在代码库中新增了一个功能（这和语义化版本中的 [`MINOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 1. **BREAKING CHANGE:** 在可选的正文或脚注的起始位置带有 `BREAKING CHANGE:` 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 [`MAJOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。破坏性变更可以是任意 _类型_ 提交的一部分。例如 `fix:`、`feat:` 和 `chore:`，乃至对于更多其它的 _类型_ 而言，它都是有效的。 1. **其它情况:** 除 `fix:` 和 `feat:` 之外的提交 _类型_ 也是被允许的，例如 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)（基于 [Angular 约定](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)）中推荐的 `chore:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` 及其他标签。我们也推荐使用`improvement`，用于对当前实现进行改进而没有添加新功能或修复错误的提交。请注意，这些标签在约定式提交规范中并不是强制性的，并且在语义化版本中没有隐式的影响（除非它们包含这种情况下本不被推荐的 BREAKING CHANGE）。
可以为提交类型添加一个围在圆括号内的作用域，以为其提供额外的上下文信息。例如 `feat(parser): adds ability to parse arrays`。 ## 示例 ### 包含了描述以及正文内有破坏性变更的提交说明 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 不包含正文的提交说明 ``` docs: correct spelling of CHANGELOG ``` ### 包含作用域的提交说明 ``` feat(lang): added polish language ``` ### 为 fix 编写的提交说明，包含（可选的） issue 编号 ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## 介绍 在软件开发中，以我个人的经验来说，bug 最常产生在应用间的边界情况中。单元测试在开源维护者已知的交互场景下工作得很好。但对于社区中各种有趣且常常是意想不到的方式使用类库的情况，它就覆盖得比较差了。 那些经历过在升级了一个依赖新的 patch 版本后，发现自己的应用竟开始抛出稳定的 500 错误流的人，都明白一个可读的提交历史（以及[理想的维护良好的 CHANGELOG](http://keepachangelog.com/en/0.3.0/)）对于排错有多重要。 约定式的提交规范提议在提交说明的基础上，引入一种标准化的轻量级约定。这个约定和 [SemVer](http://semver.org) 相吻合，它要求开发者在提交信息中描述他们所改动的新特性、bug 修复和破坏性变更。 引入这一约定后，我们可以创建一种通用的语言，更易于在项目边界间调试问题。 ## 约定式提交规范 本文中的关键词 “必须（MUST）”、“禁止（MUST NOT）”、“需要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）” ，解释参考 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 中所述。 1. 每个提交都**必须**使用类型字段前缀，它由一个名词组成，诸如 `feat` 或 `fix` ，其后接冒号（英文半角）和空格。 1. 当一个提交为应用或类库实现了新特性时，**必须**使用 `feat` 类型。 1. 当一个提交为应用修复了 bug 时，**必须**使用 `fix` 类型。 1. 可选的作用域字段**可以**在类型后提供。作用域是描述代码库中某个部分的词组，封装在圆括号中，例如： `fix(parser):`。 1. 描述字段**必须**紧接在类型或作用域前缀之后。描述指的是对代码变更的简短描述，例如： _fix: array parsing issue when multiple spaces were contained in string._ 1. 在简短描述之后，**可以**编写更长的提交正文，为代码变更提供额外的上下文信息。正文**必须**起始于描述字段结束的一个空行后。 1. 在正文结束的一个空行后，**可以**编写脚注（如果没有正文，可以编写在描述之后）。脚注**应当**为代码变更包含额外的 issue 引用信息（比如它所修复的 issue，例如： `Fixes #13`）。 1. 破坏性变更**必须**在提交的正文或脚注加以展示。一个破坏性变更**必须**包含大写的文本 `BREAKING CHANGE`，紧跟冒号和空格。 1. 在 `BREAKING CHANGE: ` 之后**必须**提供描述，以描述对 API 的变更。例如： _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 脚注**必须**只包含 `BREAKING CHANGE`、外部链接、issue 引用和其它元信息。 1. 在提交说明中，**可以**使用 `feat` 和 `fix` 之外的类型。 ## 为什么使用约定式提交 * 自动化生成 CHANGELOG。 * 基于提交的类型，自动决定语义化的版本变更。 * 向同事、公众与其他利益关系者传达变化的性质。 * 触发构建和部署流程。 * 让人们探索一个更加结构化的提交历史，以便降低对你的项目做出贡献的难度。 ## FAQ ### 在初始开发阶段我该如何处理提交说明？ 我们建议你按照假设你已发布了产品那样来处理。因为通常总 *有人* 使用你的软件，即便那是你软件开发的同事们。他们会希望知道诸如修复了什么、哪里不兼容等信息。 ### 如果提交符合多种类型我该如何操作？ 回退并尽可能创建多次提交。约定式提交的好处之一是能够促使我们做出更有组织的提交和 PR。 ### 这不会阻碍快速开发和迭代吗？ 它阻碍的是以杂乱无章的方式快速前进。它助你能在横跨多个项目以及和多个贡献者协作时长期地快速演进。 ### 约定式提交会让开发者受限于提交的类型吗（因为他们会想着已提供的类型）？ 约定式提交鼓励我们更多地使用某些类型的提交，比如 `fixes`。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。 ### 这和 SemVer 有什么关联呢？ `fix` 类型提交应当对应到 `PATCH` 版本。`feat` 类型提交应该对应到 `MINOR` 版本。带有 `BREAKING CHANGE` 的提交不管类型如何，都应该对应到 `MAJOR` 版本。 ### 我对约定式提交做了形如 `@jameswomack/conventional-commit-spec` 的扩展，该如何版本化管理这些扩展呢？ 我们推荐使用 SemVer 来发布你对于这个规范的扩展（并鼓励你创建这些扩展！） ### 如果我不小心使用了错误的提交类型，该怎么办呢？ #### 当你使用了在规范中但错误的类型时，例如将 `feat` 写成了 `fix` 在合并或发布这个错误之前，我们建议使用 `git rebase -i` 来编辑提交历史。而在发布之后，根据你使用的工具和流程不同，会有不同的清理方案。 #### 当使用了 *不* 在规范中的类型时，例如将 `feat` 写成了 `feet` 在最坏的场景下，即便提交没有满足约定式提交的规范，也不会是世界末日。这只意味着这个提交会被基于规范的工具错过而已。 ### 所有的贡献者都需要使用约定式提交规范吗？ 并不！如果你使用基于 squash 的 Git 工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交，并向主管维护者提供一份表单，用以在合并时输入合适的 git 提交信息。 ================================================ FILE: content/v1.0.0-beta.3/index.es.md ================================================ --- draft: false aliases: ["/es/"] --- # Convención de Commits 1.0.0-beta.3 ## Resumen La especificación de Commit Convencionales es una convención liviana que se aplica a los mensajes de los commits. Esta especificación proporciona un conjunto fácil de reglas para crear un historial de commits explícito; Esta convención se ajusta a [SemVer](http://semver.org), al describir las características, correcciones y cambios que rompen la compatibilidad en los mensajes de los commits. El mensaje del commit debe estar estructurado de la siguiente forma: --- ``` [ámbito opcional]: [cuerpo opcional] [nota de pie opcional] ``` ---
El commit contiene los siguientes elementos estructurales para comunicar la intención al consumidor de la librería: 1. **fix:** un commit de _tipo_ `fix` corrige un error en la base del código (se correlaciona con [`PATCH`](http://semver.org/#summary) en el versionado semántico). 1. **feat:** un commit de _tipo_ `feat` introduce nuevas características en la base del código (se correlaciona con [`MINOR`](http://semver.org/#summary) en el versionado semántico). 1. **BREAKING CHANGE:** un commit que contiene el texto `BREAKING CHANGE:` al inicio de su cuerpo opcional o la sección de nota de pie introduce un cambio que rompe la compatibilidad en el uso de la API (se correlaciona con [`MAJOR`](http://semver.org/#summary) en el versionado semántico). Un cambio en el uso de la API puede ser parte de commits de _tipo_. e.g., a `fix:`, `feat:` & `chore:` todos tipos válidos, adicional a cualquier otro _tipo_. 1. Otros: _tipos_ de commits distintos a `fix:` y `feat:` están permitidos, por ejemplo [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (basado en [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recomienda `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` y otros. También recomendamos `improvement` para commits que mejorar una implementación actual sin añadir nuevas características ni corregir errores. Tenga presente que estos tipos no son impuestos por la especificación de commits convencionales y no tienen efecto implícito en el versionado semántico (a menos que incluyan el texto BREAKING CHANGE, lo cual NO es recomendado).
Se puede agregar un ámbito al _tipo_ de commit para proveer información contextual adicional y se escribe entre paréntesis, e.g., `feat(parser): add ability to parse arrays`. ## Ejemplos ### Mensaje de commit con descripción y cambio que rompe la compatibilidad en el cuerpo ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Mensaje de commit sin cuerpo ``` docs: correct spelling of CHANGELOG ``` ### Mensaje de commit con ámbito ``` feat(lang): added polish language ``` ### Mensaje de commit para una corrección usando un número de problema (opcional) ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Especificación Las palabras “DEBE” (“MUST”), “NO DEBE” (“MUST NOT”), “REQUIERE” (“REQUIRED”), “DEBERÁ” (“SHALL”), “NO DEBERÁ” (“SHALL NOT”), “DEBERÍA” (“SHOULD”), “NO DEBERÍA” (“SHOULD NOT”), “RECOMIENDA” (“RECOMMENDED”), “PUEDE” (“MAY”) Y “OPCIONAL” (“OPTIONAL”) en este documento se deben interpretar como se describe en [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Los commits DEBEN iniciarse con un tipo que consiste en un sustantivo `feat`, `fix`, etc., seguido de dos puntos y un espacio. 1. El tipo `feat` DEBE ser usado cuando un commit agrega una nueva característica a la aplicación o librería. 1. El tipo `fix` DEBE ser usado cuando el commit representa una corrección a un error en el código de la aplicación. 1. Se PUEDE añadir un ámbito opcional después del tipo. El ámbito es una frase que describe una sección de la base del código encerrada en paréntesis, e.g., `fix(parser):` 1. Una descripción DEBE ir inmediatamente después del tipo/ámbito inicial y es una descripción corta de los cambios realizados en el código, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. Un cuerpo del commit más extenso PUEDE agregarse después de la descripción, dando información contextual adicional acerca de los cambios en el código. El cuerpo DEBE iniciar con una línea en blanco después de la descripción. 1. Una nota de pie PUEDE agregarse tras una línea en blanco después del cuerpo o después de la descripción en caso de que no se haya dado un cuerpo. La nota de pie DEBE contener referencias adicionales a los números de problemas registrados sobre el cambio del código (como el número de problema que corrige, e.g.,`Fixes #13`). 1. Los cambios que rompen la compatibilidad con la API DEBEN ser indicados al inicio de la nota de pie o el cuerpo del commit. Un cambio que rompe la compatibilidad con la API DEBE contener el texto en mayúsculas `BREAKING CHANGE`, seguido de dos puntos y espacio. 1. Una descripción se DEBE proveer después de `BREAKING CHANGE:`, describiendo qué ha cambiado en la API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. La nota de pie DEBE contener solamente el texto `BREAKING CHANGE`, vínculos externos, referencias a problemas u otra metainformación. 1. Otros tipos distintos a `feat` y `fix` PUEDEN ser usados en los mensajes de los commits. ## ¿Por qué usar Commits Convencionales? * Generación automática de CHANGELOGs. * Determinación automática de los cambios de versión (basado en los tipos de commits). * Comunicar la naturaleza de los cambios a los demás integrantes del equipo, el público o cualquier otro interesado. * Ejecutar procesos de ejecución y publicación. * Hacer más fácil a otras personas contribuir al proyecto, permitiendo explorar una historia de los commits más estructurada. ## FAQ ### ¿Cómo puedo trabajar con los mensajes de los commits en la etapa inicial de desarrollo? Recomendamos trabajar como si ya hubiera lanzado su producto. Típicamente _alguien_, incluso si son sus compañeros desarrolladores, están usando su producto. Ellos querrán saber qué se ha arreglado, qué se ha dañado, etc. ### ¿Se deben escribir los tipos de los commits en mayúscula o minúscula? Cualquiera está bien, pero es mejor ser consistente. ### ¿Qué debo hacer si un commit encaja en más de un tipo de commit? Regrese y haga múltiples commits de ser posible. Parte de los beneficios de los Commits Convencionales es la habilidad para hacer commits más organizados y así mismo PRs. ### ¿No desalienta esto el desarrollo y la iteración rápida? Desalienta moverse rápido de una forma desorganizada. Ayuda a moverse rápido a largo plazo a través de proyectos con una gran variedad de contribuidores. ### ¿Pueden los Commits Convencionales llevar a los desarrolladores a limitar el tipo de commits que hacen ya que estarán pensando en los tipos previstos? Los Commits Convencionales nos animan a hacer más de cierto tipo de commits como _fixes_. Adicionalmente, la flexibilidad de los Commits Convencionales permite a su equipo generar sus propios tipos y cambiarlos a lo largo del tiempo. ### ¿Cómo se relaciona esto con SemVer? El tipo de commit `fix` se traduce a un cambio de versión `PATCH`. El tipo de commit `feat` se traduce a un cambio de versión `MINOR`. Commits con el texto `BREAKING CHANGE`, sin importar su tipo, se traducen a un cambio de versión `MAJOR`. ### ¿Cómo puedo versionar mis extensiones a la especificación de Commits Convencionales, e.g. `@jameswomack/conventional-commit-spec`? Recomendamos usar SemVer para liberar su propia extensión a esta especificación (¡y lo animamos a hacer esta extensión!) ### ¿Qué debo hacer si por accidente uso un tipo de commit equivocado? #### Cuando utiliza un tipo que es de la especificación pero no es el correcto, e.g. `fix` en lugar de `feat` Antes de combinar o liberar el error, recomendamos usar `git rebase -i` para editar el historial de los commits. Después de que se ha liberado, la limpieza será distinta de acuerdo con las herramientas y procesos que usted use. #### Cuando se usa un tipo que no está en la especificación, e.g. `feet` instead of `feat` En el peor de los escenarios, no es el fin del mundo si aparece un commit que no cumple con las especificaciones de los commits convencionales. Simplemente, el commit será ignorado por las herramientas que se basen en esta especificación. ### ¿Deben todos los que contribuyen a mi proyecto usar esta especificación? ¡No! Si usa un flujo de trabajo basado en `squash` los líderes del proyecto pueden limpiar el mensaje en el momento en que se incorpora, sin agregar cargas adicionales a quienes contribuyen casualmente. Un flujo de trabajo común para esto es configurar su sistema de git para que haga el `squash` de manera automática de un pull request y presente al líder del proyecto un formulario para que ingrese el mensaje de commit correcto al momento de hacer el merge. ================================================ FILE: content/v1.0.0-beta.3/index.fr.md ================================================ --- draft: false aliases: ["/fr/"] --- # Conventional Commits 1.0.0-beta.3 ## Résumé La spécification de Conventional Commits est une convention légère pour des messages de commite au top. Il fournit un ensemble simple de règles pour créer un historique de commite explicite; Ce qui facilite l'écriture d'outils automatisés. Cette convention est liée à [SemVer](http://semver.org), en décrivant les fonctionnalités, les correctifs et les modifications importantes apportées aux messages des commites. Le message du commit doit être structuré comme suit: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
Le commit contient les éléments structurels suivants, permettant de communiquer à l’intention des consommateurs de votre bibliothèque: 1. **fix:** un commit de _type_ `fix` corrige un bogue dans le code (cela est en corrélation avec [`PATCH`](http://semver.org/#summary) en versioning sémantique). 1. **feat:** un commit de _type_ `feat` introduit une nouvelle fonctionnalité dans le code (cela est en corrélation avec [`MINOR`](http://semver.org/#summary) en versioning sémantique). 1. **BREAKING CHANGE:** un commit qui a le texte `BREAKING CHANGE:` qui est facultatif au début du texte ou section de pied de page introduit un changement cassant l'API (cela est en corrélation avec [`MAJOR`](http://semver.org/#summary) en versioning sémantique). Un changement radical peut faire partie des commits de _type_. par exemple, `fix:`, `feat:` & `chore:` qui sont tous valables, même additionnés les un avec les autres _type_. 1. Others: commit de _types_ autre que `fix:` et `feat:` sont autorisés, par exemple [commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) (basé sur [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommande `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, et d'autres. Nous recommandons également `improvement` pour les commits qui améliorent une implémentation en cours sans ajouter de nouvelle fonctionnalité ou correction de bogue. Remarquez que ces types ne sont pas prescrits par la spécification de Conventional Commits et n'ont aucun effet implicite dans la gestion des versions sémantiques (à moins qu'ils ne comportent une rupture, qui n'est PAS recommandée).
Un scope peut être fournie au type d'un commit, pour fournir des informations contextuelles supplémentaires et le contenu entre parenthèses, par exemple, `feat (analyseur): ajoute la possibilité d'analyser' des tableaux`. ## Exemples ### Message de commit avec description et changement radical dans le texte ``` feat: permet à l'objet de configuration fourni d'étendre d'autres configurations BREAKING CHANGE: la clé `extends` dans le fichier de configuration est maintenant utilisée pour étendre d'autres fichiers de configuration ``` ### Message commit sans corps de texte ``` docs: correction d'orthographe dans CHANGELOG ``` ### Message commit avec scope ``` feat(lang): ajout de la langue polonaise ``` ### Message commit pour un correctif à l'aide d'un numéro d'un issue (facultatif). ``` fix: fautes de frappe mineures dans le code voir le problème pour plus de détails sur les fautes de frappe corrigées fixes issue #12 ``` ## Spécification Les mots clés ”DOIT” (“MUST”), “NE DOIT PAS” (“MUST NOT”), “REQUIS” (“REQUIRED”), “NE DOIT” (“SHALL”), “NE DOIT PAS” (“SHALL NOT”), “NE DEVRAIT” (“SHOULD”), “NE DEVRAIT PAS” (“SHOULD NOT”), “RECOMMANDÉ” (“RECOMMENDED”), “PEUT” (“MAY”), et “FACULTATIF” (“OPTIONAL”) dans ce document doivent être interprétés comme décrit dans [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Les commits DOIT être préfixés par un type, qui consiste en un nom, `feat`,` fix`, etc., suivi d'un côlon et d'un espace. 1. Le type `feat` DOIT être utilisé lorsqu'un commit ajoute une nouvelle fonctionnalité à votre application. ou bibliothèque. 1. Le type `fix` DOIT être utilisé lorsqu'un commit représente un correctif pour votre application. 1. Un scope facultative PEUT être fournie après un type. Un scope est une phrase décrivant une section du code encadrée par des parenthèses, par exemple, `fix (analyseur)):` 1. Une description DOIT suivre immédiatement le préfixe type/scope. La description est une brève description des modifications du code, par exemple, _fix: problème d'analyse d'un tableau lorsque plusieurs espaces étaient contenus dans string._ 1. Un texte plus long PEUT être fourni après la description courte, fournissant des informations contextuelles supplémentaires sur les modifications du code. Le texte DOIT commencer par une ligne vide après la description. 1. Un pied de page PEUT être fourni une ligne vierge après le texte (ou après la description si le texte manque). Le pied de page DEVRAIT contenir des références de problèmes supplémentaires concernant les modifications du code (telles que les problèmes qu’il corrige, par exemple, `Fixes #13`). 1. Les changements de rupture DOIVENT être indiqués au tout début du pied de page ou de la section du corps de texte d'un commit. Un changement radical DOIT être dans le texte en majuscule `BREAKING CHANGE`, suivi de deux points et d'un espace. 1. Une description DOIT être fournie après le «BREAKING CHANGE:», décrivant la modification de l’API, par exemple, _BREAKING CHANGE: les variables d’environnement sont désormais prioritaires sur les fichiers de configuration._ 1. Le pied de page NE DOIT contenir que «BREAKING CHANGE», des liens externes, des références de publication et d'autres méta-informations. 1. Des types autres que `feat` et` fix` PEUVENT être utilisés dans vos messages de commit. ## Pourquoi Utiliser Conventional Commits * Génération automatique de CHANGELOGs. * Déterminer automatiquement un choc de version sémantique (en fonction des types de commits débarqués). * Communiquer la nature des changements aux coéquipiers, au public et aux autres parties prenantes. * Déclencher des processus de construction et de publication. * Faciliter la contribution des personnes à vos projets en leur permettant d’explorer un historique de commit plus structurée. ## FAQ ### Comment dois-je gérer les messages de commit dans la phase de développement initiale ? Nous vous recommandons de procéder comme si vous aviez déjà publié un produit. Généralement *quelqu'un*, même si ce sont vos collègues développeurs de logiciels, utilise votre logiciel. Ils voudront savoir ce qui est corrigé, ce qui casse, etc. ### Les types dans le titre des commites sont-ils en majuscules ou en minuscules? N'importe quel taille peut être utilisé, mais il est préférable d'être cohérent. ### Que dois-je faire si le commit est conforme à plusieurs types ? Revenez en arrière et faites plusieurs commits autant que possible. Une partie des avantages de Conventional Commits réside dans sa capacité à nous amener à créer des commits et des relations publiques plus organisés. ### Est-ce que cela ne décourage pas le développement rapide et l’itération rapide ? Cela décourage les commits rapides de manière désorganisée. Il vous aide à être en mesure que vous commité rapidement à long terme dans plusieurs projets avec des contributeurs variés. ### Les engagements conventionnels peuvent-ils amener les développeurs à limiter le type d’engagements qu’ils font car ils penseront aux types fournis? Conventional Commits nous encouragent à utiliser davantage certains types de commits tels que les correctifs. En dehors de cela, la flexibilité de Conventional Commits permet à votre équipe de créer ses propres types et de les modifier au fil du temps. ### Quel est le lien avec SemVer ? Les corrections de type `fix` devraient être traduites en` PATCH`. Les commits de type `feat` devraient être traduits en versions` MINOR`. Les commits avec `BREAKING CHANGE` dans les commits, quel que soit leur type, doivent être traduits en versions` MAJOR`. ### Comment dois-je mettre à jour mes extensions de la spécification de Conventional Commits, par exemple `@jameswomack/conventionnel-commit-spec` ? Nous vous recommandons d’utiliser SemVer pour publier vos propres extensions à cette spécification (et vous encourage à faire ces extensions!) ### Que dois-je faire si j'utilise accidentellement le type de commit incorrect ? #### Lorsque vous utilisez un type de commit incorrect, par exemple `fix` au lieu de` feat` Avant de fusionner ou de relâcher l'erreur, nous vous recommandons d'utiliser `git rebase -i` pour éditer l'historique des commits. Après la publication, le nettoyage sera différent selon les outils et les processus que vous utilisez. #### Lorsque vous utilisez un type qui n'est *pas* dans les spécifications, par exemple `pieds` au lieu de` feat` Dans le pire des cas, ce n'est pas la fin du monde si un commit atterrit sans respecter les spécifications de Conventional Commits. Cela signifie simplement que l’engagement sera raté par des outils basés sur les spécifications. ### Est-ce que tous mes contributeurs doivent utiliser les spécifications de Conventional Commits ? Non! Si vous utilisez un flux de travail basé sur squash sur Git, les responsables principaux peuvent nettoyer les messages des commits au fur et à mesure de leur fusion, ce qui permet de ne pas ajouter de charge de travail aux committers occasionnels. Un processus courant consiste à ce que votre système git écrase automatiquement les commits d'une demande d'extraction et présente un formulaire permettant au responsable de la maintenance d'entrer le message du commit git approprié pour la fusion. ================================================ FILE: content/v1.0.0-beta.3/index.hy.md ================================================ --- draft: false aliases: ["/hy/"] --- # Համաձայնեցված «Commit»֊ներ 1.0.0-beta.3 ## Համառոտագիր Համաձայնեցված «commit»֊ների սպեցիֆիկացիան կանոնների խումբ է «commit» մեսիջների վերաբերյալ։ Այն առաջարկում է պարզ կանոններ և պահանջներ, որոնց միջոոցով հնարավոր է ստանալ հասկանալի և ընթեռնելի «commit»֊ների պատմություն, և հեշտացնել ավտոմատացված ծրագրային ապահովման ստեղծումը, որոնք աշխատում են «commit» մեսիջների հիման վրա։ Այս կանոնները ուղիղ կապ ունեն [SemVer](http://semver.org/#summary)֊ի սպեցիֆիկացիայի հետ, և օգատգործվում են նոր ֆունցիոնալի ինտեգրման (features), սխալների ուղղումների (fixes) և հետ համատեղելիությունը խախտող փոփոխությունների (bracking changes) մասին «commit» մեսիջներում տեղելացնելու համար։ «commit» մեսիջները պետք է ունենան հետևյալ կառուցվածքը՝ --- ``` <տեսակ (type)>[ոչ պարտադիր կոնտեքստ (optional scope)]: <բացատրություն (description)> [ոչ պարտադիր մարմին (optional body)] [ոչ պարտադիր ներքևի հատված (optional footer)] ``` --- «commit»֊ները պարունակում են հետևյալ ստրուկտուրալ էլեմենտները, որոնց միջոցով ձեր ծրագրային ապահովման օգտագործողները կարող են հասկանալ ինչ է տեղի ունեցել «commit»֊ների արդյունքում՝ 1. **fix։**․ `fix` _ՏԵՍԱԿԻ_ «commit»֊ները նախատեված են սխալների ուղղումների (bug fix) մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված [`«ՓԱԹՉ»`](http://semver.org/#summary)֊ի հետ)։ 2. **feat։**․ `feat` _ՏԵՍԱԿԻ_ «commit»֊ները նախատեված են նոր ֆունկցիոնալի ինտեգրման մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված [`«ՄԻՆՈՐ»`](http://semver.org/#summary)֊ի հետ)։ 3. **BREAKING CHANGE։**․ `BREAKING CHANGE։` պարունակող «commit»֊ները (_ՄԱՐՄՆՈՒՄ_ կամ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾՈՒՄ_ ) տեղեկացնում են API֊ում արված փոփոխության մասին, որը խախտում է հետ համատեղելիությունը (breaking changes) (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված [`ՄԱԺՈՐ`](http://semver.org/#summary)֊ի հետ), `BREAKING CHANGE:`֊ը կարող է հանդիպել կամայական _ՏԵՍԱԿԻ_ «commit»֊ների հետ: 4. Ուրիշ տեսակներ. կարելի է օգտագործել նաև վերը նշվածներից տարբերվող _ՏԵՍԱԿ_ ունեցող (`fix:` և `feat:`) «commit»֊ներ, օրինակ՝ [@commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional)֊ը (հիմնված է [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)֊ի վրա) առաջարկում է օգագործել են նաև՝ `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` և այլ _ՏԵՍԱԿԻ_ «commit»֊ներ։ Մենք նաև առաջարկում ենք օգագործել `improvement`, այն _ՏԵՍԱԿԻ_ «commit»֊ների համար, որոնք բարելավում են գործող իմպլեմենտացիան առանց նոր ֆունկցիոնալի ինտեգրման և սխալների ուղղման։ Ուշադրություն դարձրեք, որ «commit»֊ների այս _ՏԵՍԱԿՆԵՐԸ_ չեն հանդիսանում համաձայնեցված «commit»֊ների սպեցիֆիկացիայի մաս և ոչ մի ձևով փոխկապակցված չեն սեմանտիկ տարբերակման սպեցիֆիկացիայի հետ (բացառություն են հանդիսանում `BREAKING CHANGE:` պարունակող «commit»֊ները)։ _ԿՈՆՏԵՔՍՏ_ կարող է ավելացվել «commit»֊ի _ՏԵՍԱԿԻՆ_ ՝ «commit»-ի կոնտեքստ սահմանելու նպատակով։ _ԿՈՆՏԵՔՍՏԸ_ պետք է լինի փակագծերի մեջ օրինակ՝ `feat(parser): add ability to parse arrays`։ ## Օրինակներ ### «commit», որը ունի _ԲԱՑԱՏՐՈՒԹՅՈՒՆ_ և _BREAKING CHANGE_ իր մարմնում ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### «commit», որը չունի _ՄԱՐՄԻՆ_ ``` docs: correct spelling of CHANGELOG ``` ### «commit», որը ունի _ԿՈՆՏԵՔՍՏ_ ``` feat(lang): add polish language ``` ### «commit», սխալի ուղղման համար, որը պարունակում է առաջադրանքի (issue) համարը ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## Սպեցիֆիկացիա Նշված բառերը՝ «ՊԵՏՔ Է» (MUST, SHALL), «ՉՊԵՏՔ Է» (MUST NOT, SHALL NOT), «ՊԱՐՏԱԴԻՐ» (REQUIRED), «ԱՆՀՐԱԺԵՇՏ Է» (SHOULD), «ԱՆՀՐԱԺԵՇՏ ՉԷ» (SHOULD NOT), «ԽՈՐՀՈՒՐԴ Է ՏՐՎՈՒՄ» (RECOMMENDED), «ԿԱՐՈՂ Է» (MAY) և «ՈՉ ՊԱՐՏԱԴԻՐ» (OPTIONAL) պետք է ինտերպրիտացվեն [RFC 2119](http://tools.ietf.org/html/rfc2119) ստանդարտին համապատասխան։ 1. «commit» մեսիջները ՊԵՏՔ Է (MUST) սկսվեն _ՏԵՍԱԿԻ_ (type) մասին նշումով, որը գոյական է (noun) և բաղկացած է լինում մեկ բառից՝ օրինակ՝ `feat`, `fix`, և այլն։ Դրան հետևում է վերջակետի նշանը և բացատը։ 2. `feat` _ՏԵՍԱԿԸ_ ՊԵՏՔ Է (MUST) օգտագործվի, երբ «commit»֊ի արդյունքում տեղի է ունենում նոր ֆունցիոնալի իմպլեմենտացիա ձեր ծրագրում կամ գրադարանում։ 3. `fix` _ՏԵՍԱԿԸ_ ՊԵՏՔ Է (MUST) օգտագործվի, երբ «commit»֊ի արդյունքում տեղի է ունենում սխալի ուղղում ձեր ծրագրում։ 4. _ԿՈՆՏԵՔՍՏԸ_ ԿԱՐՈՂ Է (MAY) ավելացվել _ՏԵՍԱԿԻՑ_ անմիջապես հետո։ _ԿՈՆՏԵՔՍՏԸ_ ՊԵՏՔ Է (MUST) գոյական լինի պարփակված փակագծերի մեջ, և նկարագրի կոդի այն հատվածը, որի վրա անդրադարձել է «commit»֊ը։ Օրինակ՝ `fix(parser): `։ 5. _ԲԱՑԱՏՐՈՒԹՅՈՒՆԸ_ (description) ՊԵՏՔ Է (MUST) լինի անմիջապես _ՏԵՍԱԿ/ԿՈՆՏԵՔՍՏ_-ին հետևող բացատից հետո։ _ԲԱՑԱՏՐՈՒԹՅՈՒՆԸ_ համառոտ ներկայանում է կոդում եղած փոփոխությունները։ Օրինակ՝ `fix: array parsing issue when multiple spaces were contained in string`։ 6. _ՄԱՐՄԻՆԸ_ (body) ԿԱՐՈՂ Է (MAY) հետևել կարճ _ԲԱՑԱՏՐՈՒԹՅԱՆԸ_ և ավելի մեծ ինֆորմացիա տրամադրել կոդում եղած փոփոխությունների մասին։ _ՄԱՐՄԻՆԸ_ ՊԵՏՔ Է (MUST) առանձնացվի _ԲԱՑԱՏՐՈՒԹՅՈՒՆԻՑ_ մեկ դատարկ տողով։ 7. _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԸ_ (footer) ԿԱՐՈՂ Է (MAY) լինել մեկ կամ մի քանի տողի տեսքով _ՄԱՐՄՆԻՑ_ անմիջապես հետո և պետք է անջատված լինի _ՄԱՐՄՆԻՑ_ մեկ դատարկ տողով։ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԸ_ ՊԵՏՔ Է (MUST) պարունակի մետա֊ինֆորմացիա «commit»֊ի մասին, (օրինակ `Fixes #13`): 8. Հետ համատեղելիությունը խախտող փոփոխությունները ՊԵՏՔ Է (MUST) պիտակավորվեն _ՄԱՐՄԻՆԻ_ կամ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ_ սկզբում։ Հետ համատեղելիությունը խախտող փոփոխությունները ՊԵՏՔ Է (MUST) պիտակավորվեն այս արտահայտությամբ՝ BREAKING CHANGE (պարտադիր մեծատառերով), որին հետևում է վերջակետ և բացատ։ 9. Հետ համատեղելիությունը խախտող փոփոխությունների նկարագիրը (ինչ է փոխվել API-ում) ՊԵՏՔ Է (MUST) հետևեն `BREAKING CHANGE: ` պիտակին։ Օրինակ՝ `BREAKING CHANGE: environment variables now take precedence over config files.`։ 10. _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ_ ՊԵՏՔ Է (MUST) միայն պարունակի `BREAKING CHANGE`, արտաքին հղումներ, խնդրի մասին նշումներ և այլ մետատվյալներ։ 11. «commit»-ների _ՏԵՍԱԿՆԵՐԸ_ ԿԱՐՈՂ ԵՆ (MAY) լինել `feat`֊ից և `fix`֊ից տարբեր։ ## Ի՞նչու օգտագործել Համաձայնեցված «Commit»֊ներ * Փոփոխությունների լոգերի (CHANGELOG) ավտոմատ գեներացում։ * Սեմանտիկ տարբերակի ավտոմատ որոշում «commit»֊ի հիման վրա։ * Տեղեկացնել փոփոխությունների բնույթի մասին թիմի անդամներին, հասարակությանը և հետաքրքրված անձանց։ * Ավտոմատացնել կառուցման (build) և հրապարակման (publish) պրոցեսները։ * Հեշտացնում է նոր մասնակիցների ինտեգրումը ձեր նախագծին, հասանելի և ստրուկտուրիզացված «commit»֊ների պատմության շնորհիվ։ ## ՀՏՀ ### Ի՞նչպես գրել «commit» մեսիջները աշխատանքի նախնական փուլերում (initial development phase): Խորհուրդ է տրվում գրել մեսիջներն այնպես, կարծես դուք արդեն հրապարակել եք պրոդուկտը։ _Որևէ մեկին_ ՝ օրինակ ձեր գործընկերներին կարող է հետաքրքիր լինել, թե ինչն է փոխվել, և ինչ նոր հետ համատեղելիությունը խախտող փոփոխություններ են եղել։ ### Ի՞նչ անել, եթե «commit»֊ը ունի ավելի քան մեկ _ՏԵՍԱԿ_։ Եթե հնարավոր է արեք իմ քանի «commit»։ Համաձայնեցված «commit»֊ների հիմնական առավելություններից մեկը՝ ավելի կազմակերպված «commit»֊ների և «PR»֊ների թողարկումն է։ ### Արդյո՞ք աշխատելու այս ձևը չի խանգարում արագ ծրագրավորմանը (rapid development) և արագ իտերացիաներին (fast iteration)։ Այս եղանակը խանգարում է ոչ կազմակերպված արագ աշխատանքին։ Դրա փոխարեն դուք արագ եք շարժվում երկարաժամկետ տեսլականով, մի քանի պրոյեկտի մասշտաբով և մի քանի մասնակիցներ առկայությամբ։ ### Արդյո՞ք համաձայնեցված «commit»֊ների _ՏԵՍԱԿՆԵՐԸ_ չեն սահմանափակի ծրագրավորողներին, քանի որ նրանք պետք է մտածեն տրամադրված _ՏԵՍԱԿՆԵՐԻ_ սահմաններում։ Համաձայնեցված «Commit»֊ների սպեցիֆիկացիան խրախուսում է այլ _ՏԵՍԱԿԻ_ «commit»֊ների օգտագործումը։ Ձեր թիմը կարող է ազատ լինել իր սեփական _ՏԵՍԱԿՆԵՐԻ_ ստեղծման մեջ և փոփոխել դրանք ժամանակի ընթացքում։ ### Ի՞նչ կապ ունի այս ամենը տարբերակման սեմանտիկ կանոնների՝ SemVer֊ի հետ։ `fix` _ՏԵՍԱԿԻ_ «commit»֊ները թողարկվում են, որպես ՓԱԹՉ. `feat` _ՏԵՍԱԿԻ_ «commit»֊ները թողարկվում են, որպես ՄԻՆՈՐ. `BREAKING CHANGE` պարունակող կամայական «commit», _ՏԵՍԱԿԻՑ_ անկախ, թողարկվում է, որպես ՄԱԺՈՐ։ ### Ինչպե՞ս է պետք տարբերակել համաձայնեցված «commit»֊ների սպեցիֆիկացիայի հիման վրա ստեղծված իմ սեփական հավելվածերը, օրինակ՝ `@jameswomack/conventional-commit-spec` Համաձայնեցված «commit»֊ների սպեցիֆիկացիայի հիման վրա ձեր հավելվածները ստեղծելիս և թողարկելիս, խորհուրդ է տրվում օգտվել՝ [`SemVer`](http://semver.org/#summary)֊ից։ (Մենք խրախուսում ենք հավելվածների ստեղծումը)։ ### Ինչ ես պետք է անեմ, երբ սխալմամբ «commit»֊ի սխալ _ՏԵՍԱԿ_ եմ օգտագործել։ #### Եթե ծեր օգտագործած _ՏԵՍԱԿԸ_ առկա է սպեցիֆիկացիայում, բայց այն սխալ է, օրինակ `fix`՝ `feat`֊ի փոխարեն։ Մինչ ձեր սխալը «mergе» անելը, կամ թողարկելը, խորհուրդ է տրվում օգտագործել `git rebase -i` և փոփոխել commit»֊ների պատմությունը։ Թողարկելուց հետո, ուղղելու եղանակները տարբեր են՝ կախված նրանից թե ինչ գործիքներից եք դուք օգտվում։ #### Եթե ձեր օգտագործած _ՏԵՍԱԿԸ_ առկա չէ սպեցիֆիկացիայում, օրինակ `feet`՝ `feat`֊ի փոխարեն։ Դա ամենևին էլ աշխարհի վերջը չէ։ Դա ուղղակի կնշանակի, որ ձեր սպեցիֆիկացիայի հիման վրա աշխատող գործիքներրը կանտեսեն այդ «commit»֊ը։ ### Իմ բոլոր գործընկերները նույնպե՞ս պետք է հետևեն համաձայնեցված «commit»֊ների սպեցիֆիկացիային։ Ոչ․ եթե ձեր աշխատանքային պրոցեսը հիմնված է «squash»֊երի վրա՝ նախագծի ղեկավարը կարող է մաքրել պատմությունը մինչև «mergе» անելը և ուշադրություն չդարձնել այդ ամենին։ Սովորաբար git֊ը ավտոմատ «squash» է անում «commit»֊ները PR֊ի ժամանակ և վերջին «commit»֊ը անում է նախագծի ղեկավարը։ ================================================ FILE: content/v1.0.0-beta.3/index.it.md ================================================ --- draft: false aliases: ["/it/"] --- # Commit Convenzionali 1.0.0-beta.3 ## Riepilogo La specifica Conventional Commits è una convenzione semplice da implementare per i messaggi dei commit. Fornisce un insieme di semplici regole per la creazione di una cronologia di commit esplicita; il che rende più facile utilizzare strumenti per automare processi. Questa convenzione si completa con [SemVer](http://semver.org), descrivendo le funzionalità, la risoluzione di errori e l'introduzione di breaking changes fatte dei commit. I messaggi dei commit dovrebbero seguire la seguente struttura: --- ``` [contesto opzionale]: [corpo opzionale] [piè di pagina opzionale] ``` ---
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicare l'intento al consumatore della libreria: 1. **fix:** un commit di _tipo_ `fix` risolve un errore nel codice (correlato al [`PATCH`](http://semver.org/#summary) in un versionamento semver). 1. **feat:** un commit di _tipo_ `feat` introduce una nuova funzionalità al codice (correlato al [`MINOR`](http://semver.org/#summary) in un versionamento semver). 1. **BREAKING CHANGE:** un commit che contiene il testo `BREAKING CHANGE:` all'inizio delle sezioni opzionali _corpo_ o _piè di pagina_, introduce una breaking API change (correlato al [`MAJOR`](http://semver.org/#summary) in un versionamento semver). Una _BREAKING CHANGE_ può essere parte di un commit di qualsiasi _tipo_. 1. Extra: sono ammessi ulteriori _tipi_ oltre `fix:` e`feat:`, per esempio [commitlint-config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (che si basa sulla [convenzione Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) raccomanda `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, ed altri. Raccomandiamo anche `improvement` per commit che migliorano un'implementazione esistente senza aggiungere nuove funzionalità o risolvere un errore. Notare che questi _tipi_ non sono mantenuti da questa specifica, e non hanno un effetto sul versionamento semver (a meno che non introducano una _BREAKING CHANGE_).
Un _contesto_ potrebbe essere aggiunto al _tipo_ di commit, al fine di offrire ulteriori informazioni contestuali. Da aggiungere tra delle parentesi tonde, Es: `feat(parser): add ability to parse arrays`. ## Esempi ### Messaggio di un commit con una _descrizione_ e una breaking change nel _corpo_ ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Messaggio di un commit senza una _descrizione_ ``` docs: correct spelling of CHANGELOG ``` ### Messaggio di un commit con uno _contesto_ ``` feat(lang): added polish language ``` ### Messaggio di un commit per un `fix` utilizzando il numero della issue (opzionale) ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Specifica Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DEVE iniziare con un _tipo_, il quale consiste in un sostantivo, `feat`, `fix`, etc., seguito dai due punti ed uno spazio. 1. Il _tipo_ `feat` DEVE essere usato quando un commit aggiunge una funzionalità all'applicazione o libreria. 1. Il _tipo_ `fix` DEVE essere usato quando un commit corregge un errore all'applicazione o libreria. 1. Un _contesto_ opzionale POTREBBE essere fornito dopo il _tipo_. Un _contesto_ rappresenta una sezione dell'applicazione o della libreria, il contenuto va racchiuso tra parentesi. Es: `fix(parser):` 1. Una _descrizione_ DEVE seguire immediatamente il _tipo_ (con eventuale _contesto_). Per _descrizione_ si intende una breve spiegazione riguardo la modifica al codice. Es: _fix: array parsing issue when multiple spaces were contained in string._ 1. Un _corpo_ del commit più lungo POTREBBE essere aggiunto dopo una breve _descrizione_, aggiungendo ulteriori informazioni contestuali riguardo le modifiche apportate al codice. Il _corpo_ DEVE iniziare dopo una linea vuota dalla _descrizione_. 1. Un _piè di pagina_ POTREBBE essere aggiunto inserendo una linea vuota dopo il _corpo_. Il _piè di pagina_ DOVREBBE contenere ulteriori informazioni riguardo le modifiche apportate al codice (come le issue che risolve, Es: `fixes #13, #5`). 1. Una _breaking changes_ DEVE essere indicata all'inizio delle sezioni _piè di pagina_ o del _corpo_ del commit. Una _breaking change_ DEVE essere scritta in maiuscolo `BREAKING CHANGE`, seguita dai due punti ed uno spazio. 1. Una descrizione DEVE essere aggiunta dopo il testo `BREAKING CHANGE: `, descrivendo il cambiamento delle API. Es: _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Il _piè di pagina_ DEVE solo contenere `BREAKING CHANGE`, collegamenti esterni, riferimenti alle issueed ulteriori meta-informazioni. 1. Un commit POTREBBE utilizzare altri _tipi_ al di fuori di `feat` e `fix` nel messaggio. ## Perchè utilizzare commit convenzionali * CHANGELOG generati automaticamente. * Determina automaticamente l'incremento di un versionamento semver (basandosi sui tipi di commit utilizzati). * Comunica la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate. * Attiva build e processi di rilascio. * Rendi più semplice alle persone contribuire al tuo progetto, dando la possibilità di esplorare una cronologia di commit più strutturata. ## FAQ ### Come dovrei comportarmi con i messaggi dei commit nella fase iniziale del progetto? Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente *qualcuno*, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc. ### I _tipi_ devono essere in maiuscolo o minuscoli? Si possono utilizzare entrambi, ma si raccomanda di essere consistenti ed utilizzarne solamente uno. ### Cosa faccio se il tipo di commit è conforme a più di un tipo? Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request organizzate meglio. ### Non scoraggia sviluppo ed iterazioni rapidi? Scoraggia a farlo in una maniere disorganizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori. ### Potrebbe Commit Convenzionali limitare gli sviluppatori a fare solamente alcuni tipi commit perchè penseranno nei tipi forniti dalla specifica? Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo. ### Come si collega a SemVer? I commit di tipo `fix` dovrebbero essere traducibili ai rilasci `PATCH`. I commit di tipo `feat` dovrebbero essere traducibili ai rilasci `MINOR`. I commit con `BREAKING CHANGE`, indipendentemente dal tipo, dovrebbero essere traducibili ai rilasci `MAJOR`. ### Come dovrei versionare le mie estensioni per la specifica Commit Convenzionali? (Es: `@jameswomack/conventional-commit-spec`) Raccomandiamo l'utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!) ### Cosa faccio se accidentalmente utilizzo un tipo di commit sbagliato? #### Quando usi un tipo della specifica ma non quello giusto (Es: `fix` invece di `feat`) Se ancora devi creare il merge o il rilascio dell'errore, raccomandiamo l'utilizzo di `git rebase -i` per riscrivere la cronologia dei commit. Nel caso ti abbia già rilasciato questa correzione dipende dai tool e processi che usi. #### Quando usi un tipo *non* della specifica (Es: `feet` invece di `feat`) Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica. ### Devono tutti i contributori seguire la specifica Commit Convenzionali? No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato. ================================================ FILE: content/v1.0.0-beta.3/index.md ================================================ --- draft: false aliases: ["/en/"] --- # Conventional Commits 1.0.0-beta.3 ## Summary The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](http://semver.org), by describing the features, fixes, and breaking changes made in commit messages. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in semantic versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning). 1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning). A BREAKING CHANGE can be part of commits of any _type_. 1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. We also recommend `improvement` for commits that improve a current implementation without adding a new feature or fixing a bug. Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`. ## Examples ### Commit message with description and breaking change in body ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit message with no body ``` docs: correct spelling of CHANGELOG ``` ### Commit message with scope ``` feat(lang): added polish language ``` ### Commit message for a fix using an (optional) issue number. ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by a colon and a space. 1. The type `feat` MUST be used when a commit adds a new feature to your application or library. 1. The type `fix` MUST be used when a commit represents a bug fix for your application. 1. An optional scope MAY be provided after a type. A scope is a phrase describing a section of the codebase enclosed in parenthesis, e.g., `fix(parser):` 1. A description MUST immediately follow the type/scope prefix. The description is a short description of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. 1. A footer MAY be provided one blank line after the body. The footer SHOULD contain additional issue references about the code changes (such as the issues it fixes, e.g.,`Fixes #13`). 1. Breaking changes MUST be indicated at the very beginning of the footer or body section of a commit. A breaking change MUST consist of the uppercase text `BREAKING CHANGE`, followed by a colon and a space. 1. A description MUST be provided after the `BREAKING CHANGE: `, describing what has changed about the API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. The footer MUST only contain `BREAKING CHANGE`, external links, issue references, and other meta-information. 1. Types other than `feat` and `fix` MAY be used in your commit messages. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've an already released product. Typically *somebody*, even if its your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### Are the types in the commit title uppercase or lowercase? Any casing may be used, but it's best to be consistent. ### What do I do if the commit conforms to more than one of the commit types? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the conventional commit specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the conventional commit specification? No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ================================================ FILE: content/v1.0.0-beta.3/index.pt-br.md ================================================ --- draft: false aliases: ["/pt-br/"] --- # Conventional Commits 1.0.0-beta.3 ## Resumo A especificação do Conventional Commits é uma convenção simples para utilizar nas mensagens de commit. Ela define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas. Esta convenção segue o [SemVer](https://semver.org), descrevendo os recursos, correções e modificações que quebram a compatibilidade nas mensagens de commit. A mensagem do commit deve ser estruturada da seguinte forma: --- ``` [escopo opcional]: [corpo opcional] [rodapé opcional] ``` ---
O commit contém os seguintes elementos estruturais, para comunicar a intenção ao utilizador da sua biblioteca: 1. **fix:** um commit do _tipo_ `fix` soluciona um problema na sua base de código (isso se correlaciona com [`PATCH`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). 1. **feat:** um commit do _tipo_ `feat` inclui um novo recurso na sua base de código (isso se correlaciona com [`MINOR`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). 1. **BREAKING CHANGE:** um commit que contém o texto `BREAKING CHANGE:`, no começo do texto do corpo opcional ou do rodapé opcional, inclui uma modificação que quebra a compatibilidade da API (isso se correlaciona com [`MAJOR`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). Uma BREAKING CHANGE pode fazer parte de commits de qualquer _tipo_. 1. Outros: _tipos_ adicionais são permitidos além de `fix:` e `feat:`, por exemplo [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (baseado [na Convenção do Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recomenda-se `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, entre outros. Também recomendamos `improvement` para commits que melhoram uma implementação atual sem adicionar um novo recurso ou consertar um bug. Observe que esses tipos não são obrigatórios pela especificação do Conventional Commits e não têm efeito implícito no versionamento semântico (a menos que incluam uma BREAKING CHANGE).
Um escopo pode ser adicionado ao tipo do commit, para fornecer informações contextuais adicionais e está contido entre parênteses, por exemplo `feat(parser): adiciona capacidade de interpretar arrays`. ## Exemplos ### Mensagem de commit com descrição e modificação que quebra a compatibilidade no corpo ``` feat: permitir que o objeto de configuração fornecido estenda outras configurações BREAKING CHANGE: a chave `extends`, no arquivo de configuração, agora é utilizada para estender outro arquivo de configuração ``` ### Mensagem de commit sem corpo ``` docs: ortografia correta de CHANGELOG ``` ### Mensagem de commit com escopo ``` feat(lang): adicionada tradução para português brasileiro ``` ### Mensagem de commit de uma correção utilizando número de ticket (opcional) ``` fix: pequenos erros de digitação no código veja o ticket para detalhes sobre os erros de digitação corrigidos fixes issue #12 ``` ## Especificação As palavras-chaves “DEVE” (“MUST”), “NÃO DEVE” (“MUST NOT”), “OBRIGATÓRIO” (“REQUIRED”), “DEVERÁ” (“SHALL”), “NÃO DEVERÁ” (“SHALL NOT”), “PODEM” (“SHOULD"), “NÃO PODEM” (“SHOULD NOT”), “RECOMENDADO” (“RECOMMENDED”), “PODE” (“MAY”) e “OPCIONAL” (“OPTIONAL”), nesse documento, devem ser interpretados como descrito na [RFC 2119](http://tools.ietf.org/html/rfc2119). 1. A mensagem de commit DEVE ser prefixado com um tipo, que consiste em um substantivo, `feat`,` fix`, etc., seguido por dois-pontos e um espaço. 1. O tipo `feat` DEVE ser usado quando um commit adiciona um novo recurso ao seu aplicativo ou biblioteca. 1. O tipo `fix` DEVE ser usado quando um commit representa a correção de um problema em seu aplicativo ou biblioteca. 1. Um escopo opcional PODE ser fornecido após um tipo. Um escopo é uma frase que descreve uma seção da base de código entre parênteses, por exemplo, `fix(parser): ` 1. Uma descrição DEVE existir após o prefixo tipo/escopo. A descrição é uma breve explicação das alterações de código, por exemplo, _fix: problema na interpretação do array quando uma string tem vários espaços._ 1. Um corpo de mensagem de commit mais longo PODE ser fornecido após a descrição curta, fornecendo informações contextuais adicionais sobre as alterações no código. O corpo DEVE começar depois de uma linha em branco após a descrição. 1. Um rodapé linhas PODE ser fornecido depois de uma linha em branco após o corpo. O rodapé PODE conter informações adicionais sobre as alterações no código (como a issue sendo corrigida, por exemplo, `Fixes #13`). 1. A modificação que quebra a compatibilidade DEVE ser indicadas logo no início do rodapé ou corpo de um commit. Uma modificação que quebra a compatibilidade DEVE consistir de um texto em maiúsculas `BREAKING CHANGE`, seguido por dois-pontos e um espaço. 1. Uma descrição DEVE ser fornecida após o texto "BREAKING CHANGE:", descrevendo o que mudou na API, por exemplo, _BREAKING CHANGE: environment variables now take precedence over config files._ 1. O rodapé DEVE conter apenas `BREAKING CHANGE`, links externos, referências a issues, e outras meta-informações. 1. Além de `feat` e `fix`, outro tipo PODE ser usados em suas mensagens de commit. ## Porque utilizar Conventional Commits * Criação automatizada de CHANGELOGs. * Determinar automaticamente um aumento de versionamento semântico (com base nos tipos de commits). * Comunicar a natureza das mudanças para colegas de equipe, o público e outras partes interessadas. * Disparar processos de build e deploy. * Facilitar a contribuição de outras pessoas em seus projetos, permitindo que eles explorem um histórico de commits mais estruturado. ## Perguntas Frequentes ### Como devo lidar com mensagens de commit na fase inicial de desenvolvimento? Recomendamos que você proceda como se já tivesse lançado um produto. Normalmente *alguém*, mesmo que seja seus colegas desenvolvedores, está usando seu software. Eles vão querer saber o que foi corrigido, o que quebra etc. ### Os tipos no título das mensagens commit são maiúsculos ou minúsculos? Qualquer opção pode ser usada, mas é melhor ser consistente. ### O que eu faço se o commit estiver de acordo com mais de um dos tipos? Volte e faça vários commits sempre que possível. Parte do benefício do Conventional Commits é a capacidade de nos levar a fazer commits e PRs mais organizados. ### Isso não desencoraja o desenvolvimento rápido e a iteração rápida? Desencoraja a movimentação rápida de forma desorganizada. Ele ajuda você a ser capaz de se mover rapidamente a longo prazo em vários projetos com vários colaboradores. ### O Conventional Commits leva os desenvolvedores a limitar o tipo de commits que eles fazem porque estarão pensando nos tipos fornecidos? O Conventional Commits nos encorajam a fazer mais commits de tipos específicos, por exemplo correções. Além disso, a flexibilidade do Conventional Commits permite que sua equipe crie seus próprios tipos e altere ao longo do tempo. ### Qual a relação com o SemVer? Commits do tipo `fix` devem ser enviados para releases `PATCH`. Commits do tipo `feat` devem ser enviados para releases `MINOR`. Commits com `BREAKING CHANGE` nas mensagens, independentemente do tipo, devem ser enviados para releases `MAJOR`. ### Como devo versionar minhas extensões utilizando a especificação do Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? Recomendamos utilizar o [SemVer](http://semver.org) para liberar suas próprias extensões para esta especificação (e incentivamos você criar essas extensões!) ### O que eu faço se acidentalmente usar o tipo errado de commit? #### Quando você usou um tipo da especificação, mas não do tipo correto, por exemplo `fix` em vez de `feat` Antes do merge ou relase com o erro, recomendamos o uso de `git rebase -i` para editar o histórico do commit. Após o release, a limpeza será diferente de acordo com as ferramentas e processos que você utiliza. #### Quando você usou um tipo que *não* é da especificação, por exemplo `feet` em vez de `feat` Na pior das hipóteses, não é o fim do mundo se um commit não atender à especificação do Conventional Commits. Significa apenas que o commit será ignorado por ferramentas baseadas nessa especificação. ### Todos os meus colaboradores precisam usar a especificação do Conventional Commits? Não! Se você usar um workflow de git baseado em squash, os mantenedores poderão limpar as mensagens de commit à medida que forem fazendo novos merges, não adicionando carga de trabalho aos committers casuais. Um workflow comum para isso é fazer com que o git faça squash dos commits automaticamente de um pull request e apresente um formulário para o mantenedor inserir a mensagem do commit apropriada para o merge. ================================================ FILE: content/v1.0.0-beta.3/index.ru.md ================================================ --- draft: false aliases: ["/ru/"] --- # Conventional Commits 1.0.0-beta.3 ## Summary Conventional Commits - это простое соглашение о том, как нужно писать сообщения commit'ов. Оно описывает простой набор правил для создания понятной истории commit'ов, а так же позволяет проще разрабатывать инструменты автоматизации, основанные на истории commit'ов. Данное соглашение совместимо с [SemVer](http://semver.org), описывая новые функции (features), исправления (fixes) и изменения, нарушающие обратную совместимость (breaking changes) в сообщениях commit'ов. Сообщения commit'ов должны быть следующей структуры: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
Commit'ы могут содержать следующие структурные элементы для сообщений пользователям вашей библиотеки: 1. **fix:** commit _типа_ `fix` исправляет ошибку (bug) в вашем коде (он соответствует [`PATCH`](http://semver.org/#summary) в SemVer) 1. **feat:** commit _типа_ `feat` добавляет новую функцию (feature) в ваш код (он соответствует [`MINOR`](http://semver.org/#summary) в SemVer). 1. **BREAKING CHANGE:** commit, который содержит текст `BREAKING CHANGE:` в начале своего не обязательного тела сообщения (body) или в подвале (footer), добавляет изменения, нарушающие обратную совместимость вашего API (он соответствует [`MAJOR`](http://semver.org/#summary) в SemVer). BREAKING CHANGE может быть частью commit'а любого _типа_. 1. Другое: commit'ы с _типами_, которые отличаются от `fix:` и `feat:`, так же разрешены. Например, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (основанный на [The Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рекомендует: `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, и другие. Мы так же рекомендуем `improvement` для commit'ов, которые вносят улучшения в текущую реализацию без добавления новых функций и исправления ошибок. Обратите внимание, что данный тип не описывается данной спецификацией и не имеет эффекта в SemVer (за исключением, когда он включает BREAKING CHANGE).
Контекст (scope) может быть объявлен рядом с типом commit'а для добавления дополнительной информации о контексте. Он должен содержаться в круглых скобках, например, `feat(parser): add ability to parse arrays`. ## Examples ### Сообщение commit'а с описанием и изменениям, нарушающим обратную совместимость, в теле ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Сообщение commit'а без тела ``` docs: correct spelling of CHANGELOG ``` ### Сообщение commit'а с указанием контекста (scope) ``` feat(lang): add polish language ``` ### Сообщение commit'а, исправляющего ошибку (fix), использующее не обязательный номер задачи (issue) в багтрекере ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## Specification Слова “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, и “OPTIONAL” в данном документе должны интерпретироваться как в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commit'ы должны (MUST) начинаться с типа, который является существительным: `feat`, `fix`, и т.д., за которым следуют не обязательное (OPTIONAL) указание контекста (scope), двоеточие и пробел. 1. Тип `feat` должен (MUST) использоваться, когда commit добавляет новый функционал (feature) в ваше приложение или библиотеку. 1. Тип `fix` должен (MUST) использоваться, когда commit исправляет ошибку (fix) в вашем приложении или библиотеки. 1. Контекст (scope) может (MAY) следовать после типа. Контекст должен (MUST) быть существительным, заключенным в круглые скобки, описывающий часть кодовой базы, которую затронул commit. Например, `fix(parser):`. 1. Описание должно (MUST) следовать через пробел сразу же после типа/контекста. Описание - это краткая выжимка об изменениях кода, например, _fix: array parsing issue when multiple spaces were contained in string._ 1. Тело (body) commit'а может (MAY) следовать после короткого описания, добавляя дополнительную информацию об изменениях в коде. Тело должно (MUST) отделяться от короткого описания одной пустой строкой. 1. Подвал (footer) может (MAY) быть добавлен и отделен от тела commit'а пустой строкой. Подвал должен (SHOULD) содержать упоминания, касающиехся изменений в коде (такие, как номера задач, которые были решение, т.е.,`Fixes #13`). 1. Описание изменений, нарушающий обратную совместимость, должно (MUST) нахожиться в самом начале подвала (footer) или тела сообщения commit'a. Описание изменений, нарушающий обратную совместимость, должно (MUST) состоять из текста `BREAKING CHANGE`, пробела и двоеточия. 1. Описание изменений, нарушающий обратную совместимость должно включаьб то, что изменилось в API. Например, _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Подвал (footer) должен (MUST) включать только внешние ссылки, номера задач (issue) и прочу мета-информацию, которая относиться к изменениям, нарушающим обратную совместимость (BREAKING CHANGE). 1. Типы отличные от `feat` и `fix` могут (MAY) быть использованы в ваших commit'ах. ## Почему нужно использовать Conventional Commits * Автоматически генерируемый CHANGELOGs. * Автоматическое определение семантической версии SemVer (на основе типов совершенных commit'ов). * Коммуникация о характере изменения между товарищами по команде, общественностью и другими заинтересованными сторонами. * Автоматически срабатываемый процесс сборки и публикации. * Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов. ## FAQ ### Как я должен писать сообщения commit'ов на начальной стадии разработки? Мы рекомендуем писать сообщения commit'ов так, как будто вы уже выпустили продукт. Как правило, *кто-то*, например, ваши коллеги, уже используют ваш код. И они хотят знать, что исправилось, что изменилось, какие нарушения обратной совместимости появились и т.д. ### В каком регистре я должен писать заголовки commit'ов? Любой регистр можно использовать, но лучше во всей истории использовать один стиль. ### Что мне делать, если commit должен содержать больше одного типа? Вернитесь назад и сделайте несколько commit'ов, если это возможно. Часть из преимуществ использования Conventional Commits - это его способность побуждать делать более организованные коммиты и PR'ы. ### Разве это не препятствует быстрому развитию и быстрой интеграции? Это препятствует быстрому развитию в неорганизованном виде. Это помогает быстро двигаться в нескольких проектах с несколькими участниками. ### Могут ли Conventional Commits заставить разработчиков ограничивать их типы commit'ов, потому что им придется думать об этих типах? Conventional Commits побуждают делать больше commit'ов с определенными типами, такими как `fix`. Кроме того, гибкость Conventional Commits позволяют вашей команде создавать свои собственные типы и изменять их с течением времени. ### Как она связывается с правилами семантического управления версиями [SemVer](http://semver.org)? `fix` тип commit'а должен быть отражен в `PATCH`-релизе. `feat` тип commit'а должен быть отражен в `MINOR`-релизе. Commit'ы с `BREAKING CHANGE` в теле или подвале, не зависимо от типа, должны быть отражены в `MAJOR`-релизе. ### Как я должен версионировать мои расширения к спецификации Conventional Commits, например, `@jameswomack/conventional-commit-spec`? Мы рекомендуем использовать [SemVer](http://semver.org) для релизов ваших расширений к этой спецификации (и рекомендуем делать эти расширения!). ### Что мне делать, если я случайно использовал не тот тип commit'а? #### Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, `fix` вместо `feat` Перед слиянием или релизом ошибки, мы рекомендуем использовать `git rebase -i` для редактирования истории commit'ов. После `release`, исправления будут отличаться в зависимости от того, какие инструменты вы используете. #### Когда вы использовали тип, *не* описанный спецификацией, например, `feet` вместо `feat` Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации. ### Должны ли все мои соавторы использовать спецификацию Conventional Commit? Нет! Если ваш рабочий процесс основа на использовании слияния (squash) Git, сопровождающий проекта может отчистить историю всех предыдущих commit'ов при их слияния, не добавляя рабочей нагрузки на случайные commit'ы. Обычно, рабочий процесс строится на том, что ваша система Git автоматически объединяет (squash) все предыдущие commit'ы пред перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового commit'а. ================================================ FILE: content/v1.0.0-beta.3/index.zh-hans.md ================================================ --- draft: false aliases: ["/zh/", "/zh-hans/"] --- # 约定式提交 1.0.0-beta.3 ## 概述 约定式提交规范是一种基于提交消息的轻量级约定。 它提供了一组用于创建清晰的提交历史的简单规则； 这使得编写基于规范的自动化工具变得更容易。 这个约定与 [SemVer](http://semver.org) 相吻合， 在提交信息中描述新特性、bug 修复和破坏性变更。 提交说明的结构如下所示： --- ``` <类型>[可选的作用域]: <描述> [可选的正文] [可选的脚注] ``` ---
提交说明包含了下面的结构化元素，以向类库使用者表明其意图： 1. **fix:** _类型_ 为 `fix` 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 [`PATCH`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 2. **feat:** _类型_ 为 `feat` 的提交表示在代码库中新增了一个功能（这和语义化版本中的 [`MINOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 3. **BREAKING CHANGE:** 在可选的正文或脚注的起始位置带有 `BREAKING CHANGE:` 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 [`MAJOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 破坏性变更可以是任意 _类型_ 提交的一部分。 1. **其它情况:** 除 `fix:` 和 `feat:` 之外的提交 _类型_ 也是被允许的，例如 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)（基于 [Angular 约定](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)）中推荐的 `chore:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` 及其他标签。 我们也推荐使用`improvement`，用于对当前实现进行改进而没有添加新功能或修复错误的提交。 请注意，这些标签在约定式提交规范中并不是强制性的。并且在语义化版本中没有隐式的影响（除非他们包含 BREAKING CHANGE）。
可以为提交类型添加一个围在圆括号内的作用域，以为其提供额外的上下文信息。例如 `feat(parser): adds ability to parse arrays.`。 ## 示例 ### 包含了描述以及正文内有破坏性变更的提交说明 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 不包含正文的提交说明 ``` docs: correct spelling of CHANGELOG ``` ### 包含作用域的提交说明 ``` feat(lang): added polish language ``` ### 为 fix 编写的提交说明，包含（可选的） issue 编号 ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## 约定式提交规范 本文中的关键词 “必须（MUST）”、“禁止（MUST NOT）”、“需要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）” ，解释参考 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 中所述。 1. 每个提交都**必须**使用类型字段前缀，它由一个名词组成，诸如 `feat` 或 `fix` ，其后接冒号（英文半角）和空格。 1. 当一个提交为应用或类库实现了新特性时，**必须**使用 `feat` 类型。 1. 当一个提交为应用修复了 bug 时，**必须**使用 `fix` 类型。 1. 可选的作用域字段**可以**在类型后提供。作用域是描述代码库中某个部分的词组，封装在圆括号中，例如： `fix(parser):`。 1. 描述字段**必须**紧接在类型或作用域前缀之后。 描述指的是对代码变更的简短描述，例如： _fix: array parsing issue when multiple spaces were contained in string._ 1. 在简短描述之后，**可以**编写更长的提交正文，为代码变更提供额外的上下文信息。正文**必须**起始于描述字段结束的一个空行后。 1. 在正文结束的一个空行后，**可以**编写脚注。 脚注**应当**为代码变更包含额外的 issue 引用信息（比如它所修复的 issue，例如： `Fixes #13`）。 1. 破坏性变更**必须**在提交的正文或脚注加以展示。一个破坏性变更**必须**包含大写的文本 `BREAKING CHANGE`，紧跟冒号和空格。 1. 在 `BREAKING CHANGE: ` 之后**必须**提供描述，以描述对 API 的变更。例如： _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 脚注**必须**只包含 `BREAKING CHANGE`、外部链接、issue 引用和其它元信息。 1. 在提交说明中，**可以**使用 `feat` 和 `fix` 之外的类型。 ## 为什么使用约定式提交 * 自动化生成 CHANGELOG。 * 基于提交的类型，自动决定语义化的版本变更。 * 向同事、公众与其他利益关系者传达变化的性质。 * 触发构建和部署流程。 * 让人们探索一个更加结构化的提交历史，以便降低对你的项目做出贡献的难度。 ## FAQ ### 在初始开发阶段我该如何处理提交说明？ 我们建议你按照假设你已发布了产品那样来处理。因为通常总 *有人* 使用你的软件，即便那是你软件开发的同事们。他们会希望知道诸如修复了什么、哪里不兼容等信息。 ### 提交标题中的类型是大写还是小写? 大小写都可以，但最好是一致的。 ### 如果提交符合多种类型我该如何操作？ 回退并尽可能创建多次提交。约定式提交的好处之一是能够促使我们做出更有组织的提交和 PR。 ### 这不会阻碍快速开发和迭代吗？ 它阻碍的是以杂乱无章的方式快速前进。它助你能在横跨多个项目以及和多个贡献者协作时长期地快速演进。 ### 约定式提交会让开发者受限于提交的类型吗（因为他们会想着已提供的类型）？ 约定式提交鼓励我们更多地使用某些类型的提交，比如 `fixes`。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。 ### 这和 SemVer 有什么关联呢？ `fix` 类型提交应当对应到 `PATCH` 版本。`feat` 类型提交应该对应到 `MINOR` 版本。带有 `BREAKING CHANGE` 的提交不管类型如何，都应该对应到 `MAJOR` 版本。 ### 我对约定式提交做了形如 `@jameswomack/conventional-commit-spec` 的扩展，该如何版本化管理这些扩展呢？ 我们推荐使用 SemVer 来发布你对于这个规范的扩展（并鼓励你创建这些扩展！） ### 如果我不小心使用了错误的提交类型，该怎么办呢？ #### 当你使用了在规范中但错误的类型时，例如将 `feat` 写成了 `fix` 在合并或发布这个错误之前，我们建议使用 `git rebase -i` 来编辑提交历史。而在发布之后，根据你使用的工具和流程不同，会有不同的清理方案。 #### 当使用了 *不* 在规范中的类型时，例如将 `feat` 写成了 `feet` 在最坏的场景下，即便提交没有满足约定式提交的规范，也不会是世界末日。这只意味着这个提交会被基于规范的工具错过而已。 ### 所有的贡献者都需要使用约定式提交规范吗？ 并不！如果你使用基于 squash 的 Git 工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。 有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交，并向主管维护者提供一份表单，用以在合并时输入合适的 git 提交信息。 ================================================ FILE: content/v1.0.0-beta.4/index.fr.md ================================================ --- draft: false aliases: ["/fr/"] --- # Conventional Commits 1.0.0-beta.4 ## Résumé La spécification de Conventional Commits est une convention légère pour des messages de commit au top. Il fournit un ensemble simple de règles pour créer un historique de commit explicite; Ce qui facilite l'écriture d'outils automatisés. Cette convention est liée à [SemVer](http://semver.org), en décrivant les fonctionnalités, les correctifs et les modifications importantes apportées aux messages de commit. Le message du commit doit être structuré comme suit: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
Le commit contient les éléments structurels suivants, permettant de communiquer à l’intention des consommateurs de votre bibliothèque: 1. **fix:** un commit de _type_ `fix` corrige un bogue dans le code (cela est en corrélation avec [`PATCH`](http://semver.org/#summary) en versioning sémantique). 1. **feat:** un commit de _type_ `feat` introduit une nouvelle fonctionnalité dans le code (cela est en corrélation avec [`MINOR`](http://semver.org/#summary) en versioning sémantique). 1. **BREAKING CHANGE:** un commit qui a le texte `BREAKING CHANGE:` qui est facultatif au début du texte ou section de pied de page introduit un changement cassant l'API (cela est en corrélation avec [`MAJOR`](http://semver.org/#summary) en versioning sémantique). Un changement radical peut faire partie des commits de n'importe quel type. 1. Others: commit de _types_ autre que `fix:` et `feat:` sont autorisés, par exemple [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (basé sur [the Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) recommande `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, et d'autres. Nous recommandons également `improvement` pour les commits qui améliorent une implémentation en cours sans ajouter de nouvelle fonctionnalité ou correction de bogue. Remarquez que ces types ne sont pas prescrits par la spécification de Conventional Commits et n'ont aucun effet implicite dans la gestion des versions sémantiques (à moins qu'ils ne comportent un BREAKING CHANGE).
Un scope peut être fourni au type d'un commit, pour fournir des informations contextuelles supplémentaires et le contenu entre parenthèses, par exemple, `feat (analyseur): ajout possibilité d'analyser des tableaux`. ## Exemples ### Message de commit avec description et changement radical dans le texte ``` feat: permet à l'objet de configuration fourni d'étendre d'autres configurations BREAKING CHANGE: la clé `extends` dans le fichier de configuration est maintenant utilisée pour étendre d'autres fichiers de configuration ``` ### Message du commit avec l'option `!` attire l'attention sur un changement radical ``` chore!: supprimer le nœud 6 de la matrice de test BREAKING CHANGE: suppression du nœud 6 qui arrive en fin de vie en avril ``` ### Message commit sans corps de texte ``` docs: correction d'orthographe dans CHANGELOG ``` ### Message commit avec scope ``` feat(lang): ajout de la langue polonaise ``` ### Message commit pour un correctif à l'aide d'un numéro d'un issue (facultatif). ``` fix: fautes de frappe mineures dans le code voir le problème pour plus de détails sur les fautes de frappe corrigées fixes issue #12 ``` ## Spécification Les mots clés ”DOIT” (“MUST”), “NE DOIT PAS” (“MUST NOT”), “REQUIS” (“REQUIRED”), “NE DOIT” (“SHALL”), “NE DOIT PAS” (“SHALL NOT”), “NE DEVRAIT” (“SHOULD”), “NE DEVRAIT PAS” (“SHOULD NOT”), “RECOMMANDÉ” (“RECOMMENDED”), “PEUT” (“MAY”), et “FACULTATIF” (“OPTIONAL”) dans ce document doivent être interprétés comme décrit dans [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Les commits DOIVENT être préfixés par un type, qui consiste en un nom, `feat`,` fix`, etc., suivi de deux points et d'un espace. 1. Le type `feat` DOIT être utilisé lorsqu'un commit ajoute une nouvelle fonctionnalité à votre application. ou bibliothèque. 1. Le type `fix` DOIT être utilisé lorsqu'un commit représente un correctif pour votre application. 1. Un scope facultative PEUT être fourni après un type. Un scope est une phrase décrivant une section du code encadrée par des parenthèses, par exemple, `fix (analyseur):` 1. Une description DOIT suivre immédiatement le préfixe type/scope. La description est une brève description des modifications du code, par exemple, _fix: problème d'analyse d'un tableau lorsque plusieurs espaces étaient contenus dans string._ 1. Un texte plus long PEUT être fourni après la description courte, fournissant des informations contextuelles supplémentaires sur les modifications du code. Le texte DOIT commencer par une ligne vide après la description. 1. Un pied de page d'une ou plusieurs lignes PEUT être précédé d'une ligne blanche après le corps. Le pied de page DOIT contenir des méta-informations. À propos du commit, par exemple, demandes d'extraction associées, relecteurs, modifications importantes, avec une méta-information par ligne. 1. Les changements de rupture DOIVENT être indiqués au tout début de la section corps, ou au début d’une ligne dans la section pied de page. Un changement radical DOIT être dans le texte en majuscule BREAKING CHANGE, suivi de deux points et d'un espace. 1. Une description DOIT être fournie après le `BREAKING CHANGE: `, décrivant la modification de l’API, par exemple, _BREAKING CHANGE: les variables d’environnement sont désormais prioritaires sur les fichiers de configuration._ 1. Des types autres que `feat` et` fix` PEUVENT être utilisés dans vos messages de commit. 1. Les unités d'informations constituant les commits classiques NE DOIVENT PAS être considérées comme sensibles à la casse par les développeurs, à l'exception de BREAKING CHANGE, qui DOIT être en majuscule. 1. Un `!` PEUT être ajouté avant le `:` dans le préfixe type/scope, pour attirer davantage l'attention sur la modification des modifications. `BREAKING CHANGE: la description` DOIT également être incluse dans le corps ou pied de page, avec le `!` dans le préfixe. ## Pourquoi Utiliser Conventional Commits * Génération automatique de CHANGELOGs. * Déterminer automatiquement un choc de version sémantique (en fonction des types de commits débarqués). * Communiquer la nature des changements aux coéquipiers, au public et aux autres parties prenantes. * Déclencher des processus de construction et de publication. * Faciliter la contribution des personnes à vos projets en leur permettant d’explorer un historique de commit plus structurée. ## FAQ ### Comment dois-je gérer les messages de commit dans la phase de développement initiale ? Nous vous recommandons de procéder comme si vous aviez déjà publié un produit. Généralement *quelqu'un*, même si ce sont vos collègues développeurs de logiciels, utilise votre logiciel. Ils voudront savoir ce qui est corrigé, ce qui casse, etc. ### Les types dans le titre des commits sont-ils en majuscules ou en minuscules? N'importe quelle taille peut être utilisée, mais il est préférable d'être cohérent. ### Que dois-je faire si le commit est conforme à plus d'un type de commit? Revenez en arrière et faites plusieurs commits autant que possible. Une partie des avantages de Conventional Commits réside dans sa capacité à nous inciter à créer des commits et des PR plus organisés. ### Est-ce que cela ne décourage pas le développement rapide et l’itération rapide ? Cela décourage les commits rapides de manière désorganisée. Il vous aide à être en mesure que vous commité rapidement à long terme dans plusieurs projets avec des contributeurs variés. ### Les engagements conventionnels peuvent-ils amener les développeurs à limiter le type d’engagements qu’ils font car ils penseront aux types fournis? Conventional Commits nous encouragent à utiliser davantage certains types de commits tels que les correctifs. En dehors de cela, la flexibilité de Conventional Commits permet à votre équipe de créer ses propres types et de les modifier au fil du temps. ### Quel est le lien avec SemVer ? Les corrections de type `fix` devraient être traduites en` PATCH`. Les commits de type `feat` devraient être traduits en versions` MINOR`. Les commits avec `BREAKING CHANGE` dans les commits, quel que soit leur type, doivent être traduits en versions` MAJOR`. ### Comment dois-je mettre à jour mes extensions de la spécification de Conventional Commits, par exemple `@jameswomack/conventionnel-commit-spec` ? Nous vous recommandons d’utiliser SemVer pour publier vos propres extensions à cette spécification (et vous encourage à faire ces extensions !) ### Que dois-je faire si j'utilise accidentellement le type de commit incorrect ? #### Lorsque vous utilisez un type de commit incorrect, par exemple `fix` au lieu de` feat` Avant de fusionner ou de libérer l'erreur, nous vous recommandons d'utiliser `git rebase -i` pour éditer l'historique du commit. Après la publication, le nettoyage sera différent selon les outils et les processus que vous utilisez. #### Lorsque vous utilisez un type qui n'est *pas* dans les spécifications, par exemple `feet` au lieu de` feat` Dans le pire des cas, ce n'est pas la fin du monde si un commit atterrit sans respecter les spécifications de Conventional Commits. Cela signifie simplement que l’engagement sera raté par des outils basés sur les spécifications. ### Est-ce que tous mes contributeurs doivent utiliser les spécifications de Conventional Commits ? Non ! Si vous utilisez un flux de travail basé sur squash sur Git, les responsables principaux peuvent nettoyer les messages des commits au fur et à mesure de leur fusion, ce qui permet de ne pas ajouter de charge de travail aux committers occasionnels. Un processus courant consiste à ce que votre système git écrase automatiquement les commits d'une demande d'extraction et présente un formulaire permettant au responsable de la maintenance d'entrer le message du commit git approprié pour la fusion. ================================================ FILE: content/v1.0.0-beta.4/index.hy.md ================================================ --- draft: false aliases: ["/hy/"] --- # Համաձայնեցված «Commit»֊ներ 1.0.0-beta.4 ## Համառոտագիր Համաձայնեցված «commit»֊ների սպեցիֆիկացիան կանոնների խումբ է «commit» մեսիջների վերաբերյալ։ Այն առաջարկում է պարզ կանոններ և պահանջներ, որոնց միջոոցով հնարավոր է ստանալ հասկանալի և ընթեռնելի «commit»֊ների պատմություն, և հեշտացնել ավտոմատացված ծրագրային ապահովման ստեղծումը, որոնք աշխատում են «commit» մեսիջների հիման վրա։ Այս կանոնները ուղիղ կապ ունեն [SemVer](http://semver.org/#summary)֊ի սպեցիֆիկացիայի հետ, և օգատգործվում են նոր ֆունցիոնալի ինտեգրման (features), սխալների ուղղումների (fixes) և հետ համատեղելիությունը խախտող փոփոխությունների (bracking changes) մասին «commit» մեսիջներում տեղելացնելու համար։ «commit» մեսիջները պետք է ունենան հետևյալ կառուցվածքը՝ --- ``` <տեսակ (type)>[ոչ պարտադիր կոնտեքստ (optional scope)]: <բացատրություն (description)> [ոչ պարտադիր մարմին (optional body)] [ոչ պարտադիր ներքևի հատված (optional footer)] ``` --- «commit»֊ները պարունակում են հետևյալ ստրուկտուրալ էլեմենտները, որոնց միջոցով ձեր ծրագրային ապահովման օգտագործողները կարող են հասկանալ ինչ է տեղի ունեցել «commit»֊ների արդյունքում՝ 1. **fix։**․ `fix` _ՏԵՍԱԿԻ_ «commit»֊ները նախատեված են սխալների ուղղումների (bug fix) մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված [`«ՓԱԹՉ»`](http://semver.org/#summary)֊ի հետ)։ 2. **feat։**․ `feat` _ՏԵՍԱԿԻ_ «commit»֊ները նախատեված են նոր ֆունկցիոնալի ինտեգրման մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված [`«ՄԻՆՈՐ»`](http://semver.org/#summary)֊ի հետ)։ 3. **BREAKING CHANGE։**․ `BREAKING CHANGE։` պարունակող «commit»֊ները (_ՄԱՐՄՆՈՒՄ_ կամ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾՈՒՄ_ ) տեղեկացնում են API֊ում արված փոփոխության մասին, որը խախտում է հետ համատեղելիությունը (breaking changes) (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված [`ՄԱԺՈՐ`](http://semver.org/#summary)֊ի հետ), `BREAKING CHANGE:`֊ը կարող է հանդիպել կամայական _ՏԵՍԱԿԻ_ «commit»֊ների հետ: 4. Ուրիշ տեսակներ. կարելի է օգտագործել նաև վերը նշվածներից տարբերվող _ՏԵՍԱԿ_ ունեցող (`fix:` և `feat:`) «commit»֊ներ, օրինակ՝ [@commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional)֊ը (հիմնված է [Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)֊ի վրա) առաջարկում է օգագործել են նաև՝ `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` և այլ _ՏԵՍԱԿԻ_ «commit»֊ներ։ Մենք նաև առաջարկում ենք օգագործել `improvement`, այն _ՏԵՍԱԿԻ_ «commit»֊ների համար, որոնք բարելավում են գործող իմպլեմենտացիան առանց նոր ֆունկցիոնալի ինտեգրման և սխալների ուղղման։ Ուշադրություն դարձրեք, որ «commit»֊ների այս _ՏԵՍԱԿՆԵՐԸ_ չեն հանդիսանում համաձայնեցված «commit»֊ների սպեցիֆիկացիայի մաս և ոչ մի ձևով փոխկապակցված չեն սեմանտիկ տարբերակման սպեցիֆիկացիայի հետ (բացառություն են հանդիսանում `BREAKING CHANGE:` պարունակող «commit»֊ները)։ _ԿՈՆՏԵՔՍՏ_ կարող է ավելացվել «commit»֊ի _ՏԵՍԱԿԻՆ_ ՝ «commit»-ի կոնտեքստ սահմանելու նպատակով։ _ԿՈՆՏԵՔՍՏԸ_ պետք է լինի փակագծերի մեջ օրինակ՝ `feat(parser): add ability to parse arrays`։ ## Օրինակներ ### «commit», որը ունի _ԲԱՑԱՏՐՈՒԹՅՈՒՆ_ և _BREAKING CHANGE_ իր մարմնում ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### «commit», որում կա `!` _BREAKING CHANGE_ ֊ի վրա ուշադրություն գրավելու համար ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### «commit», որը չունի _ՄԱՐՄԻՆ_ ``` docs: correct spelling of CHANGELOG ``` ### «commit», որը ունի _ԿՈՆՏԵՔՍՏ_ ``` feat(lang): add polish language ``` ### «commit», սխալի ուղղման համար, որը պարունակում է առաջադրանքի (issue) համարը ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## Սպեցիֆիկացիա Նշված բառերը՝ «ՊԵՏՔ Է» (MUST, SHALL), «ՉՊԵՏՔ Է» (MUST NOT, SHALL NOT), «ՊԱՐՏԱԴԻՐ» (REQUIRED), «ԱՆՀՐԱԺԵՇՏ Է» (SHOULD), «ԱՆՀՐԱԺԵՇՏ ՉԷ» (SHOULD NOT), «ԽՈՐՀՈՒՐԴ Է ՏՐՎՈՒՄ» (RECOMMENDED), «ԿԱՐՈՂ Է» (MAY) և «ՈՉ ՊԱՐՏԱԴԻՐ» (OPTIONAL) պետք է ինտերպրիտացվեն [RFC 2119](http://tools.ietf.org/html/rfc2119) ստանդարտին համապատասխան։ 1. «commit» մեսիջները ՊԵՏՔ Է (MUST) սկսվեն _ՏԵՍԱԿԻ_ (type) մասին նշումով, որը գոյական է (noun) և բաղկացած է լինում մեկ բառից՝ օրինակ՝ `feat`, `fix`, և այլն։ Դրան հետևում է ՈՉ ՊԱՐՏԱԴԻՐ (OPTIONAL) _ԿՈՆՏԵՔՍՏԸ_ (scope) և ՊԱՐՏԱԴԻՐ (REQUIRED) վերջակետի նշանը և բացատը։ 2. `feat` _ՏԵՍԱԿԸ_ ՊԵՏՔ Է (MUST) օգտագործվի, երբ «commit»֊ի արդյունքում տեղի է ունենում նոր ֆունցիոնալի իմպլեմենտացիա ձեր ծրագրում կամ գրադարանում։ 3. `fix` _ՏԵՍԱԿԸ_ ՊԵՏՔ Է (MUST) օգտագործվի, երբ «commit»֊ի արդյունքում տեղի է ունենում սխալի ուղղում ձեր ծրագրում։ 4. _ԿՈՆՏԵՔՍՏԸ_ ԿԱՐՈՂ Է (MAY) ավելացվել _ՏԵՍԱԿԻՑ_ անմիջապես հետո։ _ԿՈՆՏԵՔՍՏԸ_ ՊԵՏՔ Է (MUST) գոյական լինի պարփակված փակագծերի մեջ, և նկարագրի կոդի այն հատվածը, որի վրա անդրադարձել է «commit»֊ը։ Օրինակ՝ `fix(parser): `։ 5. _ԲԱՑԱՏՐՈՒԹՅՈՒՆԸ_ (description) ՊԵՏՔ Է (MUST) լինի անմիջապես _ՏԵՍԱԿ/ԿՈՆՏԵՔՍՏ_-ին հետևող բացատից հետո։ _ԲԱՑԱՏՐՈՒԹՅՈՒՆԸ_ համառոտ ներկայանում է կոդում եղած փոփոխությունները։ Օրինակ՝ `fix: array parsing issue when multiple spaces were contained in string`։ 6. _ՄԱՐՄԻՆԸ_ (body) ԿԱՐՈՂ Է (MAY) հետևել կարճ _ԲԱՑԱՏՐՈՒԹՅԱՆԸ_ և ավելի մեծ ինֆորմացիա տրամադրել կոդում եղած փոփոխությունների մասին։ _ՄԱՐՄԻՆԸ_ ՊԵՏՔ Է (MUST) առանձնացվի _ԲԱՑԱՏՐՈՒԹՅՈՒՆԻՑ_ մեկ դատարկ տողով։ 7. _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԸ_ (footer) ԿԱՐՈՂ Է (MAY) լինել մեկ կամ մի քանի տողի տեսքով _ՄԱՐՄՆԻՑ_ անմիջապես հետո և պետք է անջատված լինի _ՄԱՐՄՆԻՑ_ մեկ դատարկ տողով։ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԸ_ ՊԵՏՔ Է (MUST) պարունակի մետա֊ինֆորմացիա «commit»֊ի մասին, օրինակ՝ «pull» հարցումների, ստուգողների (reviewers), հետ համատեղելիությունը խախտող փոփոխությունների և ալյն։ Մետա֊ինֆորմացիայի ամեն մասը զբաղեցնում է մեկ տող։ 8. Հետ համատեղելիությունը խախտող փոփոխությունները ՊԵՏՔ Է (MUST) պիտակավորվեն _ՄԱՐՄԻՆԻ_ կամ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ_ սկզբում։ Հետ համատեղելիությունը խախտող փոփոխությունները ՊԵՏՔ Է (MUST) պիտակավորվեն այս արտահայտությամբ՝ BREAKING CHANGE (պարտադիր մեծատառերով), որին հետևում է վերջակետ և բացատ։ 9. Հետ համատեղելիությունը խախտող փոփոխությունների նկարագիրը (ինչ է փոխվել API-ում) ՊԵՏՔ Է (MUST) հետևեն `BREAKING CHANGE: ` պիտակին։ Օրինակ՝ `BREAKING CHANGE: environment variables now take precedence over config files.`։ 10. «commit»-ների _ՏԵՍԱԿՆԵՐԸ_ ԿԱՐՈՂ ԵՆ (MAY) լինել `feat`֊ից և `fix`֊ից տարբեր։ 11. Համաձայնեցված «commit»֊ներում ներկայացված բաղադրիչները, ՉՊԵՏՔ Է (MUST NOT) դիտարկվեն, որպես ռեգիստրից կախված (case sensitive), բացառություն է միայն `BREAKING CHANGE`֊ը, որը միշտ պետք է լինի մեծատառերով։ 12. `!` նշանը ԿԱՐՈՂ Է (MAY) ավելացվել `:` նշանից առաջ և _ՏԵՍԱԿ/ԿՈՆՏԵՔՍՏ_-ից հետո, որպեսզի ուշադրություն գրավի հետ համատեղելիությունը խախտող փոփոխությունների վրա։ `BREAKING CHANGE: description` տողը ևս ՊԵՏՔ Է (MUST) ավելացվի _ՄԱՐՄԻՆԻ_ կամ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ_ սկզբում, եթե օգտագործվել է `!` նշանը։ ## Ի՞նչու օգտագործել Համաձայնեցված «Commit»֊ներ * Փոփոխությունների լոգերի (CHANGELOG) ավտոմատ գեներացում։ * Սեմանտիկ տարբերակի ավտոմատ որոշում «commit»֊ի հիման վրա։ * Տեղեկացնել փոփոխությունների բնույթի մասին թիմի անդամներին, հասարակությանը և հետաքրքրված անձանց։ * Ավտոմատացնել կառուցման (build) և հրապարակման (publish) պրոցեսները։ * Հեշտացնում է նոր մասնակիցների ինտեգրումը ձեր նախագծին, հասանելի և ստրուկտուրիզացված «commit»֊ների պատմության շնորհիվ։ ## ՀՏՀ ### Ի՞նչպես գրել «commit» մեսիջները աշխատանքի նախնական փուլերում (initial development phase): Խորհուրդ է տրվում գրել մեսիջներն այնպես, կարծես դուք արդեն հրապարակել եք պրոդուկտը։ _Որևէ մեկին_ ՝ օրինակ ձեր գործընկերներին կարող է հետաքրքիր լինել, թե ինչն է փոխվել, և ինչ նոր հետ համատեղելիությունը խախտող փոփոխություններ են եղել։ ### Ի՞նչ անել, եթե «commit»֊ը ունի ավելի քան մեկ _ՏԵՍԱԿ_։ Եթե հնարավոր է արեք իմ քանի «commit»։ Համաձայնեցված «commit»֊ների հիմնական առավելություններից մեկը՝ ավելի կազմակերպված «commit»֊ների և «PR»֊ների թողարկումն է։ ### Արդյո՞ք աշխատելու այս ձևը չի խանգարում արագ ծրագրավորմանը (rapid development) և արագ իտերացիաներին (fast iteration)։ Այս եղանակը խանգարում է ոչ կազմակերպված արագ աշխատանքին։ Դրա փոխարեն դուք արագ եք շարժվում երկարաժամկետ տեսլականով, մի քանի պրոյեկտի մասշտաբով և մի քանի մասնակիցներ առկայությամբ։ ### Արդյո՞ք համաձայնեցված «commit»֊ների _ՏԵՍԱԿՆԵՐԸ_ չեն սահմանափակի ծրագրավորողներին, քանի որ նրանք պետք է մտածեն տրամադրված _ՏԵՍԱԿՆԵՐԻ_ սահմաններում։ Համաձայնեցված «Commit»֊ների սպեցիֆիկացիան խրախուսում է այլ _ՏԵՍԱԿԻ_ «commit»֊ների օգտագործումը։ Ձեր թիմը կարող է ազատ լինել իր սեփական _ՏԵՍԱԿՆԵՐԻ_ ստեղծման մեջ և փոփոխել դրանք ժամանակի ընթացքում։ ### Ի՞նչ կապ ունի այս ամենը տարբերակման սեմանտիկ կանոնների՝ SemVer֊ի հետ։ `fix` _ՏԵՍԱԿԻ_ «commit»֊ները թողարկվում են, որպես ՓԱԹՉ. `feat` _ՏԵՍԱԿԻ_ «commit»֊ները թողարկվում են, որպես ՄԻՆՈՐ. `BREAKING CHANGE` պարունակող կամայական «commit», _ՏԵՍԱԿԻՑ_ անկախ, թողարկվում է, որպես ՄԱԺՈՐ։ ### Ինչպե՞ս է պետք տարբերակել համաձայնեցված «commit»֊ների սպեցիֆիկացիայի հիման վրա ստեղծված իմ սեփական հավելվածերը, օրինակ՝ `@jameswomack/conventional-commit-spec` Համաձայնեցված «commit»֊ների սպեցիֆիկացիայի հիման վրա ձեր հավելվածները ստեղծելիս և թողարկելիս, խորհուրդ է տրվում օգտվել՝ [`SemVer`](http://semver.org/#summary)֊ից։ (Մենք խրախուսում ենք հավելվածների ստեղծումը)։ ### Ինչ ես պետք է անեմ, երբ սխալմամբ «commit»֊ի սխալ _ՏԵՍԱԿ_ եմ օգտագործել։ #### Եթե ծեր օգտագործած _ՏԵՍԱԿԸ_ առկա է սպեցիֆիկացիայում, բայց այն սխալ է, օրինակ `fix`՝ `feat`֊ի փոխարեն։ Մինչ ձեր սխալը «mergе» անելը, կամ թողարկելը, խորհուրդ է տրվում օգտագործել `git rebase -i` և փոփոխել commit»֊ների պատմությունը։ Թողարկելուց հետո, ուղղելու եղանակները տարբեր են՝ կախված նրանից թե ինչ գործիքներից եք դուք օգտվում։ #### Եթե ձեր օգտագործած _ՏԵՍԱԿԸ_ առկա չէ սպեցիֆիկացիայում, օրինակ `feet`՝ `feat`֊ի փոխարեն։ Դա ամենևին էլ աշխարհի վերջը չէ։ Դա ուղղակի կնշանակի, որ ձեր սպեցիֆիկացիայի հիման վրա աշխատող գործիքներրը կանտեսեն այդ «commit»֊ը։ ### Իմ բոլոր գործընկերները նույնպե՞ս պետք է հետևեն համաձայնեցված «commit»֊ների սպեցիֆիկացիային։ Ոչ․ եթե ձեր աշխատանքային պրոցեսը հիմնված է «squash»֊երի վրա՝ նախագծի ղեկավարը կարող է մաքրել պատմությունը մինչև «mergе» անելը և ուշադրություն չդարձնել այդ ամենին։ Սովորաբար git֊ը ավտոմատ «squash» է անում «commit»֊ները PR֊ի ժամանակ և վերջին «commit»֊ը անում է նախագծի ղեկավարը։ ================================================ FILE: content/v1.0.0-beta.4/index.id.md ================================================ --- draft: false aliases: ["/id/"] --- # Conventional Commits 1.0.0-beta.4 ## Ringkasan Conventional Commits adalah perjanjian sederhana tentang cara menulis pesat komit. Ini menjelaskan sekumpulan aturan sederhana untuk membuat riwayat komit yang jelas; yang memudahkan untuk membuat alat automatis di atasnya. Perjanjian ini cocok dengan [SemVer](http://semver.org), dengan menjelaskan suatu fitur (features), perbaikan (fixes), merusak perubahan (breaking changes) yang dimuat dalam pesan komit. Pesan komit harus tersusun sebagai berikut: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
Komit berisi elemen struktural sebagai berikut, untuk menyampaikan maksud kepada konsumen perpustakaan anda: 1. **fix:** komit _tipe_ `fix` untuk perbaikan celah (bug) dalam kode anda (ini berkolerasi dengan [`PATCH`](http://semver.org/#summary) di semantic versioning). 1. **feat:** komit _tipe_ `feat` memperkenalkan suatu fitur (feature) baru dalam kode anda (ini berkolerasi dengan [`MINOR`](http://semver.org/#summary) di semantic versioning). 1. **BREAKING CHANGE:** komit yang berisi teks `BREAKING CHANGE:` di awal bagian opsi badan atau kaki mengenalkan merusak perubahan API (ini berkolerasi dengan [`MAJOR`](http://semver.org/#summary) di semantic versioning). BREAKING CHANGE dapat menjadi bagian dari komit _tipe_ apapun. 1. Lainya: komit dengan _tipe-tipe_ selain dari `fix:` and `feat:` diperbolehkan, misalnya [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (berdasarkan pada [Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) direkomendasikan `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, dan lainya. Kami juga merekomendasikan `improvement` untuk komit yang meningkatkan implementasi saat ini tanpa menambahkan fitur baru atau memperbaiki celah (bug). Perhatikan bahwa tipe-tipe ini tidak di amanatkan oleh spesifikasi conventional commits, dan tidak ada efek implisit dalam semantic versioning (kecuali mereka termasuk BREAKING CHANGE).
Cakupan dapat disediakan ke tipe komit. untuk memberikan informasi kontekstual tambahan dan terkandung dalam kurung, misalnya, `feat(parser): add ability to parse arrays`. ## Examples ### Pesan komit dengan deskripsi dan breaking change di badan ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Pesan komit dengan opsi `!` untuk menarik perhatian pada breaking change ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### Pesan komit tanpa badan ``` docs: correct spelling of CHANGELOG ``` ### Pesan komit dengan cakupan ``` feat(lang): add polish language ``` ### Pesan komit untuk perbaikan menggunakan (opsi) nomor masalah. ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## Spesifikasi Kata “HARUS”, “TIDAK BOLEH”, “DIBUTUHKAN”, “SEHARUSNYA”, “JANGAN SAMPAI”, “SEBAIKNYA”, “SEBAIKNYA TIDAK”, “DIREKOMENDASIKAN”, “BISA”, dan “OPSIONAL” di dokumen ini sesuai dengan [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Komit HARUS (MUST) diawali dengan tipe, yang terdiri dari kata benda, `feat`, `fix`, dll., diikuti dengan OPSIONAL (OPTIONAL) cakupan, dan DIBUTUHKAN terminal colon dan spasi. 1. tipe `feat` HARUS (MUST) digunakan ketika komit menambahkan fitur baru ke apilkasi atau perpustakaan anda. 1. tipe `fix` HARUS (MUST) digunakan ketika komit mewakili perbaikan celah (bug) untuk aplikasi anda. 1. Cakupan BISA (MAY) disediakan setelah tipe. Cakupan HARUS terdiri dari kata benda yang menggambarkan bagian dari kode yang dikelilingi tanda kurung, misalnya, `fix(parser):` 1. Deskripsi HARUS (MUST) segera mengikuti spasi setelah awalan tipe/cakupan. Deskripsi adalah ringkasan singkat dari perubahan kode, misalnya, _fix: array parsing issue when multiple spaces were contained in string._ 1. Komit badan yang leibh panjang BISA (MAY) disediakan setelah deskripsi pendek, memberikan informasi kontekstual tambahan tentang perubahan kode. Badan HARUS (MUST) diawalin dengan satu barus kosong setelah deskripsi. 1. Kaki satu atau lebih baris BISA (MAY) disediakan satu baris kosong setelah badan. kaki HARUS (MUST) berisi tentang meta-informasi tentang perubahan, misalnya, related pull-requests, reviewers, breaking changes, dengan satu informasi meta per baris. 1. Breaking changes HARUS (MUST) di tunjukan di bagian paling awal dari bagian tubuh, atau di awal baris di bagian kaki. Breaking change HARUS terdiri dari huruf besar BREAKING CHANGE, diikuti dengan colon dan spasi. 1. Deskripsi HARUS (MUST) disediakan setelah `BREAKING CHANGE: `, menggambarkan apa yang telah berubah tentang API, misalnya, _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Tipe selain `feat` dan `fix` BISA (MAY) digunakan dalam pesan komit anda. 1. Unit-unit informasi yang membentuk conventional commits TIDAK BOLEH (MUST NOT) diperlakukan case sensitif oleh pelaksana, dengan pengecualian BREAKING CHANGE yang HARUS (MUST) huruf besar. 1. `!` BISA (MAY) ditambakan sebelum `:` dalam awalan tipe/cakupan, untuk menarik perhatian pada breaking changes. `BREAKING CHANGE: description` HARUS (MUST) dimasukan kedalam badan atau kaki,bersama dengan `!` di awalan. ## Mengapa menggunakan Conventional Commits * Secara automatis menghasilkan CHANGELOGs. * Secara automatis menentukan versi semantic (Berdasarkan tipe komit yang dilakukan). * Mengkomunikasikan sifat perubahan kepada rekan setim, publik, dan pemangku kepentingan lainnya. * Memicu proses pembuatan dan publikasi. * Mempermudah orang untuk berkontribusi pada proyek Anda, dengan memungkinkan mereka untuk menjelajah riwayat komit yang lebih terstruktur. ## FAQ ### Bagaimana saya harus berurusan dengan pesan komit pada fase pengembangan awal? Kami menyarankan Anda melanjutkan seolah-olah Anda sudah merilis produk. Biasanya *seseorang*, bahkan jika itu sesama pengembang perangkat lunak Anda, menggunakan perangkat lunak Anda. Mereka ingin tahu apa yang diperbaiki, apa yang rusak, dll. ### Apakah tipe dalam komit judul huruf besar atau kecil? Casing apa pun dapat digunakan, tetapi yang terbaik adalah konsisten. ### Apa yang harus saya lakukan jika komit sesuai dengan lebih dari satu tipe komit? Kembalilah dan buat beberapa komit kapan pun memungkinkan. Bagian dari manfaat Conventional Commits adalah kemampuannya mendorong kami untuk membuat komitmen dan PR yang lebih terorganisir. ### Tidakkah ini menghambat pengembangan yang cepat dan iterasi yang cepat? Ini mencegah bergerak cepat dengan cara yang tidak teratur. Ini membantu Anda dapat bergerak cepat jangka panjang di berbagai proyek dengan kontributor yang bervariasi. ### Mungkinkah Komitmen Konvensional membuat pengembang membatasi jenis komitmen yang mereka buat karena mereka akan memikirkan jenis yang disediakan? Komitmen Konvensional mendorong kita untuk membuat lebih banyak jenis komitmen tertentu seperti perbaikan. Selain itu, fleksibilitas Komitmen Konvensional memungkinkan tim Anda untuk membuat tipe mereka sendiri dan mengubah tipe-tipe itu seiring waktu. ### Bagaimana ini berhubungan dengan SemVer? Komit tipe `fix` harus diterjemahkan ke rilis `PATCH`. Komit tipe `feat` harus diterjemahkan ke rilis `MINOR`. Komit dengan `BREAKING CHANGE` dalam komit, apa pun jenisnya, harus diterjemahkan ke rilis `MAJOR`. ### Bagaimana cara saya memberi versi ekstensi saya ke Spesifikasi Komitmen Konvensional, mis. `@jameswomack/commit-spec-konvensional`? Kami sarankan menggunakan SemVer untuk merilis ekstensi Anda sendiri ke spesifikasi ini (dan mendorong Anda untuk membuat ekstensi ini!) ### Apa yang harus saya lakukan jika saya secara tidak sengaja menggunakan tipe komit yang salah? #### Saat Anda menggunakan jenis yang memiliki spesifikasi tetapi bukan jenis yang benar, misalnya, `fix` bukan `feat` Sebelum menggabungkan atau merilis kesalahan, sebaiknya gunakan `git rebase -i` untuk mengedit riwayat komit. Setelah rilis, pembersihan akan berbeda sesuai dengan alat dan proses apa yang Anda gunakan. #### Saat Anda menggunakan jenis *bukan* spesifikasi, mis. `feet` bukannya `feat` Dalam skenario terburuk, ini bukan akhir dunia jika komit mendarat yang tidak memenuhi spesifikasi conventional commit. Ini berarti komit akan dilewatkan oleh alat yang didasarkan pada spesifikasi. ### Apakah semua kontributor saya perlu menggunakan spesifikasi commit konvensional? Tidak! Jika Anda menggunakan alur kerja berbasis squash di pengelola Git dapat membersihkan pesan komit saat mereka digabung — menambahkan tidak ada beban kerja ke komuter biasa. Alur kerja umum untuk ini adalah membuat sistem git Anda secara otomatis squash melakukan dari permintaan tarikan dan menyajikan formulir bagi pengelola utama untuk memasukkan pesan git commit yang tepat untuk penggabungan. ================================================ FILE: content/v1.0.0-beta.4/index.it.md ================================================ --- draft: false aliases: ["/it/"] --- # Commit Convenzionali 1.0.0-beta.4 ## Riepilogo La specifica Conventional Commits è una convenzione semplice da implementare per i messaggi dei commit. Fornisce un insieme di semplici regole per la creazione di una cronologia di commit esplicita; il che rende più facile utilizzare strumenti per automare processi. Questa convenzione si completa con [SemVer](http://semver.org), descrivendo le funzionalità, la risoluzione di errori e l'introduzione di breaking changes fatte dei commit. I messaggi dei commit dovrebbero seguire la seguente struttura: --- ``` [contesto opzionale]: [corpo opzionale] [piè di pagina opzionale] ``` ---
Il commit contiene i seguenti elementi strutturali, allo scopo di comunicare l'intento al consumatore della libreria: 1. **fix:** un commit di _tipo_ `fix` risolve un errore nel codice (correlato al [`PATCH`](http://semver.org/#summary) in un versionamento semver). 1. **feat:** un commit di _tipo_ `feat` introduce una nuova funzionalità al codice (correlato al [`MINOR`](http://semver.org/#summary) in un versionamento semver). 1. **BREAKING CHANGE:** un commit che contiene il testo `BREAKING CHANGE:` all'inizio delle sezioni opzionali _corpo_ o _piè di pagina_, introduce una breaking API change (correlato al [`MAJOR`](http://semver.org/#summary) in un versionamento semver). Una _BREAKING CHANGE_ può essere parte di un commit di qualsiasi _tipo_. 1. Extra: sono ammessi ulteriori _tipi_ oltre `fix:` e`feat:`, per esempio [commitlint-config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (che si basa sulla [convenzione Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) raccomanda `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, ed altri. Raccomandiamo anche `improvement` per commit che migliorano un'implementazione esistente senza aggiungere nuove funzionalità o risolvere un errore. Notare che questi _tipi_ non sono mantenuti da questa specifica, e non hanno un effetto sul versionamento semver (a meno che non introducano una _BREAKING CHANGE_).
Un _contesto_ potrebbe essere aggiunto al _tipo_ di commit, al fine di offrire ulteriori informazioni contestuali. Da aggiungere tra delle parentesi tonde, Es: `feat(parser): add ability to parse arrays`. ## Esempi ### Messaggio di un commit con una _descrizione_ e una breaking change nel _corpo_ ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Messaggio di un commit con un opzionale `!` per attirare l'attenzione su una breaking change ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### Messaggio di un commit senza una _descrizione_ ``` docs: correct spelling of CHANGELOG ``` ### Messaggio di un commit con uno _contesto_ ``` feat(lang): added polish language ``` ### Messaggio di un commit per un `fix` utilizzando il numero della issue (opzionale) ``` fix: minor typos in code see the issue for details on the typos fixed fixes issue #12 ``` ## Specifica Le parole “DEVE”, “NON DEVE”, “RICHIESTO”, “DOVRÀ”, “NON DOVRÀ”, “DOVREBBE”, “NON DOVREBBE”, “RACCOMANDATO”, “POTREBBE” e “OPZIONALE” devo essere interpretata come da specifica [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Un commit DEVE iniziare con un _tipo_, il quale consiste in un sostantivo, `feat`, `fix`, etc., e DEVE essere seguito dai due punti ed uno spazio. 1. Il _tipo_ `feat` DEVE essere usato quando un commit aggiunge una funzionalità all'applicazione o libreria. 1. Il _tipo_ `fix` DEVE essere usato quando un commit corregge un errore all'applicazione o libreria. 1. Un _contesto_ opzionale POTREBBE essere fornito dopo il _tipo_. Un _contesto_ rappresenta una sezione dell'applicazione o della libreria, il contenuto va racchiuso tra parentesi. Es: `fix(parser):` 1. Una _descrizione_ DEVE seguire immediatamente il _tipo_ (con eventuale _contesto_). Per _descrizione_ si intende una breve spiegazione riguardo la modifica al codice. Es: _fix: array parsing issue when multiple spaces were contained in string._ 1. Un _corpo_ del commit più lungo POTREBBE essere aggiunto dopo una breve _descrizione_, aggiungendo ulteriori informazioni contestuali riguardo le modifiche apportate al codice. Il _corpo_ DEVE iniziare dopo una linea vuota dalla _descrizione_. 1. Un _piè di pagina_ POTREBBE essere aggiunto inserendo una linea vuota dopo il _corpo_. Il _piè di pagina_ DOVREBBE contenere ulteriori informazioni riguardo le modifiche apportate al codice (come le issue che risolve, Es: `fixes #13, #5`). 1. Una _breaking changes_ DEVE essere indicata all'inizio delle sezioni _piè di pagina_ o del _corpo_ del commit. Una _breaking change_ DEVE essere scritta in maiuscolo `BREAKING CHANGE`, seguita dai due punti ed uno spazio. 1. Una descrizione DEVE essere aggiunta dopo il testo `BREAKING CHANGE: `, descrivendo il cambiamento delle API. Es: _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Il _piè di pagina_ DEVE solo contenere `BREAKING CHANGE`, collegamenti esterni, riferimenti alle issueed ulteriori meta-informazioni. 1. Un commit POTREBBE utilizzare altri _tipi_ al di fuori di `feat` e `fix` nel messaggio. 1. La convenzione NON DEVE tener conto del maiuscolo o minuscolo, ad eccezione di `BREAKING CHANGE` che DEVE sempre essere maiuscolo. 1. Un `!` POTREBBE essere aggiunti prima del prefisso`:` nel _tipo_/_contesto_, per attirare notificare l'introduzione di una breaking change. `BREAKING CHANGE: description` DEVE essere aggiungto nel _copro_ o _piè di pagina_ se un `!` è presente. ## Perchè utilizzare commit convenzionali * CHANGELOG generati automaticamente. * Determina automaticamente l'incremento di un versionamento semver (basandosi sui tipi di commit utilizzati). * Comunica la natura dei cambiamenti a colleghi, pubblico, o altri parti interessate. * Attiva build e processi di rilascio. * Rendi più semplice alle persone contribuire al tuo progetto, dando la possibilità di esplorare una cronologia di commit più strutturata. ## FAQ ### Come dovrei comportarmi con i messaggi dei commit nella fase iniziale del progetto? Raccomandiamo di procedere come se il tuo prodotto sia già stato rilasciato. Tipicamente *qualcuno*, anche i tuoi colleghi, stanno utilizzando il tuo software. Loro vorranno sapere cosa sia stato risolto, cosa si sia rotto etc. ### I _tipi_ devono essere in maiuscolo o minuscoli? Si possono utilizzare entrambi, ma si raccomanda di essere consistenti ed utilizzarne solamente uno. ### Cosa faccio se il tipo di commit è conforme a più di un tipo? Torna indietro e dividi in più commit dove puoi. Parte del beneficio di usare Commit Convenzionali è quello di spingerti a fare commit e pull request organizzate meglio. ### Non scoraggia sviluppo ed iterazioni rapidi? Scoraggia a farlo in una maniere disorganizzata. Inoltre ti aiuterà a muoverti più velocemente su più progetti con diversi contributori. ### Potrebbe Commit Convenzionali limitare gli sviluppatori a fare solamente alcuni tipi commit perchè penseranno nei tipi forniti dalla specifica? Commit Convenzionali ti incoraggia nel fare più di certi tipi di commit. Inoltre la flessibilità di Commit Convenzionali consente al tuo team di inventare i propri tipi e cambiarli nel tempo. ### Come si collega a SemVer? I commit di tipo `fix` dovrebbero essere traducibili ai rilasci `PATCH`. I commit di tipo `feat` dovrebbero essere traducibili ai rilasci `MINOR`. I commit con `BREAKING CHANGE`, indipendentemente dal tipo, dovrebbero essere traducibili ai rilasci `MAJOR`. ### Come dovrei versionare le mie estensioni per la specifica Commit Convenzionali? (Es: `@jameswomack/conventional-commit-spec`) Raccomandiamo l'utilizzo di SemVer per rilasciare la tua estensione (crea delle estensioni!) ### Cosa faccio se accidentalmente utilizzo un tipo di commit sbagliato? #### Quando usi un tipo della specifica ma non quello giusto (Es: `fix` invece di `feat`) Se ancora devi creare il merge o il rilascio dell'errore, raccomandiamo l'utilizzo di `git rebase -i` per riscrivere la cronologia dei commit. Nel caso ti abbia già rilasciato questa correzione dipende dai tool e processi che usi. #### Quando usi un tipo *non* della specifica (Es: `feet` invece di `feat`) Non è la fine del mondo se un commit non segue la specifica Commit Convenzionali. Semplicemente il commit verrà ignorato dai tool che sono basati su questa specifica. ### Devono tutti i contributori seguire la specifica Commit Convenzionali? No. Se usi un workflow basato sugli squash di Git, i mantenitori possono pulire i messaggi dei commit mentre vengono inseriti nel branch principale (merge), non aggiungendo alcun carico di lavoro ai committer occasionali. Un workflow comune è quello di unire (con lo squash) automaticamente i commit dalle pull request e far utilizzare un form ai mantenitori per riscrivere un messaggio più adeguato. ================================================ FILE: content/v1.0.0-beta.4/index.ja.md ================================================ --- draft: false aliases: ["/ja/"] --- # Conventional Commits 1.0.0-beta.4 ## 概要 Conventional Commitsの仕様は、コミットメッセージのための軽量の規約です。 明示的なコミット履歴を作成するための簡単なルールを提供します、この規則に従うことで自動化ツールの導入を簡単にします。 この規約は[SemVer](http://semver.org)と組み合わせることで、コミットメッセージへ機能、修正、重大な変更を入れることで、さらに詳細な説明を可能にします。 コミットメッセージは次のような形にする必要があります --- 原文： ``` [optional scope]: [optional body] [optional footer] ``` 訳： ``` <型>[任意 範囲]: <説明> [任意 本文] [任意 脚注] ``` ---
コミットにはあなたのライブラリの利用者に思想を伝えるために、次の構造要素を持ちます： 1. **fix:** _型_ `fix` はコードベースのバグにパッチを当てる場合です。（これは セマンティックバージョン管理における[`PATCH`](http://semver.org/#summary)に相当します) 1. **feat:** _型_ `feat` はコードベースに新しい機能を追加した場合です。(これはセマンティックバージョン管理における [`MINOR`](http://semver.org/#summary)に相当します) 1. **BREAKING CHANGE:** 本体または脚注の冒頭に `BREAKING CHANGE:` という内容があるコミットは、APIの重大な変更を意味できます。(セマンティックバージョン管理における[`MAJOR`](http://semver.org/#summary)に相当します) `BREAKING CHANGE` はあらゆる _型_ のコミットに含めることができます。 1. Others: `fix:` and `feat:` 以外のコミット _型_ を許容します、例えば [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) ([Angularの規約](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)ベース)は `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, などがあります。 新しい機能の追加やバグを修正ではなく、現在の実装を改善するコミットには `improvement` をおすすめします。 これらの _型_ はconventional commitsで強制されているものではなく、セマンティックバージョン管理に暗黙的な影響も与えません。（それが、BREAKING CHANGEを含めない限り）
コミットの _型_ には、追加の情報として _範囲_ を追加することができ、それは括弧で囲みます。例 `feat(parser): add ability to parse arrays` ## 例 ### 説明と重大な変更を含む本文のメッセージをコミットに含める ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 重大な変更であることに気づいてもらうために `!` を付けてメッセージをコミットできる ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### 本文無しでメッセージをコミットする ``` docs: correct spelling of CHANGELOG ``` ### _範囲_ のあるメッセージをコミットする ``` feat(lang): add polish language ``` ### (オプション) issueの番号を修正用のコミットメッセージに含めます ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## 仕様 この文書における次の各キーワード「しなければならない（ MUST ）」、 「してはならない（ MUST NOT ）」、「要求されている（ REQUIRED ）」、 「することになる（ SHALL ）」、「することはない（ SHALL NOT ）」、 「する必要がある（ SHOULD ）」、「しないほうがよい（ SHOULD NOT ）」、 「推奨される（ RECOMMENDED ）」、「してもよい（ MAY ）」、 「選択できる（ OPTIONAL ）」は、 [RFC 2119 (JPNIC 日本語)](https://www.nic.ad.jp/ja/tech/ipa/RFC2119JA.html) で述べられているように 解釈されるべきものです。 1. コミットは _型_ から始まり、次に選択できる（ OPTIONAL ） _範囲_ と、末尾に要求されている（ REQUIRED ）コロンとスペースで成り立ちます。 1. コミットがあなたのアプリケーションやライブラリに新しい機能を追加するとき、 _型_ は`feat`にしなければならない（ MUST ）。 1. コミットがあなたのアプリケーションのためのバグ修正を表すとき、 _型_ は `fix`にしなければならない（ MUST ）。 1. _範囲_ は _型_ の後に記述してもよい（ MAY ）。 _範囲_ は括弧で囲まれたコードベースのセクションを記述する名詞にしなければならない（ MUST ）。例： `fix(構文解析ツール): ' 1. _説明_ は型/範囲の直後にしなければならない（ MUST ）。 _説明_ はコード変更の要約です。 _fix：文字列に複数の空白がある場合の配列解析における問題_ 1. 短い _説明_ の後に、より長いコミットの本文を追加してもよく（ MAY ）、コード変更に関する追加の情報を提供することができます。 本文は、_説明_ の下に1行の空行を追加しなければならない（ MUST ）。 1. 1行以上の _脚注_ は、本文の後ろに1行の空白行を入れてもよい（ MAY ）。 _脚注_ はコミットに関するメタ情報、例えば関連するプルリクエスト、レビュアー、変更の中断などを1行につき1つのメタ情報として含めなければならない（ MUST ）。 1. 重大な変更(`BREAKING CHANGE`)は、本文セクションの一番最初、または脚注の先頭にしなければいけません（ MUST ）。 重大な変更は大文字のテキスト `BREAKING CHANGE` と続くコロンとスペースから構成されなければいけません（ MUST ）。 1. APIについて何が変わったのかを説明する`BREAKING CHANGE:`の後には説明を書かなければいけません（ MUST ）。 例、 _BREAKING CHANGE: 環境変数が設定ファイルよりも優先されるようになりました。_ 1. `feat`と`fix` 以外の _型_ をあなたのコミットメッセージに仕様してもよい（ MAY ）。 1. Conventional Commitsを構成する情報の単位は、必ず大文字の`BREAKING CHANGE`を除いて、実装側は大文字と小文字を別の物して扱ってはいけない（ MUST NOT ） 1. さらに重大な変更の注意を引くために、 _種類_ / _範囲_ の `:` の前に `!`を追加することができます（ MAY ）。`BREAKING CHANGE: description`は、接頭辞の`!`とともに、本文または脚注にも含めなければなりません（ MUST ）。 ## 何故 Conventional Commits を使うのか * 変更履歴(CHANGELOG)を自動的に生成できます。 * semantic version単位で自動的に履歴を纏めれます（コミットされた _型_ に基づきます）。 * チームメイトや一般のユーザー、およびその他の利害関係者へ変更の内容を伝えることができる。 * ビルドおよび公開プロセスをトリガーにできます。 * より構造化されたコミット履歴を調査できるようにすることで、人々があなたのプロジェクトに貢献しやすくなります。 ## よくある質問 ### 初期の開発段階ではコミットメッセージをどのように扱うべきですか？ すでに製品をリリースしているかのように進めることをお勧めします。 あなたの仲間のソフトウェア開発者であっても、普通は *誰か* があなたのソフトウェアを使っています。 何が修正されたのか、何が壊れたのかなどを知りたいでしょう。 ### コミットタイトル(1行目)の型は大文字か小文字のどちらが良いですか？ どちらでも問題はありません、一貫性を保つことが最善です。 ### コミットが複数のコミットタイプ( _型_ )に準拠している場合はどうすればいいですか？ 可能な限り前に戻り複数のコミットに分割します。 Conventional Commits の利点の一つは、より組織化されたコミットとプルリクエストを行う事を可能にする事です。 ### これは開発速度とインテグレーションを遅くしたりはしませんか？ 無秩序にただ早く開発することはお勧めではありません。 それはあなたがさまざまな貢献者との複数のプロジェクト間で長期的に素早く動けるようにするのを助けます。 ### Conventional Commitsで開発者は提供された _型_ を検討することになるため、コミットの _型_ を制限することができますか？ Conventional Commitsは、修正などの特定の _型_ のコミットメントを行うように促します。 それ以外の点では、Conventional Commitsの柔軟性により、あなたのチームは彼ら自身の _型_ を新しく作り、時間の経過とともにそれらの _型_ を変更することもできます。 ### これはSemVerとどのような関係を持っていますか？ `fix` _型_ のコミットは`PATCH`リリースへ変換します。 `feat` _型_ のコミットは`MINOR`リリースに変換します。 _型_ にかかわらずコミット内で `BREAKING CHANGE`を使ったコミットは`MAJOR`リリースに変換するべきでしょう。 ### 私の拡張仕様をどのようにしてConventional Commitsの仕様にバージョンアップするべきでしょうか？、例： `@jameswomack/conventional-commit-spec` SemVerを使用して、この仕様に対する独自の拡張仕様をリリースすることをお勧めします（そしてこれらの拡張仕様を作成することをお勧めします）。 ### 間違ったコミットタイプを使用してしまった時はどうしたらいいですか？ #### 仕様的に正しい型だが意味を間違った _型_ を使用した場合、例えば `feat`の代わりに`fix` 間違いをマージやリリースする前に、コミット履歴を編集する`git rebase -i`を使うことを勧めます。 リリース後、どのツールやプロセスを使用するかによってクリーンアップは異なってくるでしょう。 #### 仕様に *ない* _型_ を使った時、例えば`feat` ではなく`feet` 最悪のシナリオはコミットが conventional commit の仕様を満たさない場合です、しかしそれは世界の終わりではありません。 それは単に仕様に基づいているツールによってコミットが見逃されるだけでしかありません。 ### 貢献者全員が conventional commit を使用する必要がありますか？ いいえ！ Gitでsquashベースのワークフローを使用するなら、主要メンテナはマージ時にコミットメッセージをクリーンアップすることができるため、通常のコミッタには作業負荷がかかりません。 また一般的なワークフローの場合は、あなたのgitシステムが自動的にpull requestからコミットを破棄し、主要メンテナにマージのための適切なgit commitメッセージを入力するためのフォームを提示することです。 ================================================ FILE: content/v1.0.0-beta.4/index.ko.md ================================================ --- draft: false aliases: ["/ko/"] --- # Conventional Commits 1.0.0-beta.4 ## 개요 Conventional Commits 스펙은 커밋 메시지에 곁들여진 가벼운 컨벤션으로 명확한 커밋 히스토리를 생성하기 위한 간단한 규칙을 제공합니다. 이렇게 만들어진 커밋 히스토리를 이용하여 더 쉽게 자동화된 도구를 만들 수 있습니다. 이 컨벤션은 커밋 메세지에 신규 기능 추가, 문제 수정, 커다란 변화가 있음을 기술함으로써 [유의적 버전(Semantic Versioning)](https://semver.org/lang/ko/)과 일맥상통한 면이 있습니다. 커밋 메세지는 다음과 같은 구조가 되어야 합니다: --- ``` <타입>[적용 범위(선택 사항)]: <설명> [본문(선택 사항)] [꼬리말(선택 사항)] ``` ---
커밋에는 라이브러리를 사용하는 사람들에게 의도를 전달하기 위해 다음과 같은 구조적 요소가 포함되어 있습니다. 1. **fix:** 코드베이스에서 버그를 패치하는 `fix` _타입_ 의 커밋 (이는 유의적 버전에서의 [`PATCH`](http://semver.org/#summary)와 관련이 있습니다). 1. **feat:** 코드베이스에서 새 기능이 추가되는 `feat` _타입_ 의 커밋 (이는 유의적 버전에서의 [`MINOR`](http://semver.org/#summary)와 관련이 있습니다). 1. **BREAKING CHANGE:** 본문이나 꼬리말의 시작 부분에 `BREAKING CHANGE:`이라는 문자열을 가진 커밋은 커다란 API 변경 있다는 것을 의미합니다 (이는 유의적 버전에서의 [`MAJOR`](http://semver.org/#summary)와 관련이 있습니다). 어떤 커밋 타입이라도 BREAKING CHANGE는 해당 커밋의 일부가 될 수 있습니다. 1. 다른 타입: `fix:`와 `feat:` 이외의 커밋 타입을 말합니다, 예를 들어 [앵귤러 컨벤션](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)을 기반으로 하는 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)에서는 `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` 등의 타입을 사용할 것을 권고하고 있습니다. 또한, 새로운 기능이나 버그 수정없이 현재 구현체를 개선하는 커밋에 대해서는 `improvement`을 사용하는 것이 좋습니다. 이 타입은 BREAKING CHANGES를 포함하지 않는 한 Conventional Commits 스펙에 의해 강제되는 부분은 아니고 유의적 버전에도 암묵적 영향을 가지지 않습니다.
추가적인 문맥 정보를 제공하기 위한 목적으로 사용되는 적용 범위는 커밋의 타입에 덧붙여질 수 있는데 괄호 안에 포함됩니다, 예를 들면, `feat(parser): add ability to parse arrays`. ## 예제 ### 본문에 설명과 BREAKING CHANGE를 가지는 커밋 메세지 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### BREAKING CHANGE에 주의를 주기 위해 옵션인 `!`를 포함한 커밋 메세지 ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### 본문이 없는 커밋 메세지 ``` docs: correct spelling of CHANGELOG ``` ### 적용 범위를 가지는 커밋 메세지 ``` feat(lang): add polish language ``` ### 옵션인 이슈 번호를 가진 fix 타입의 커밋 메세지 ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## 규격 이 문서에서 언급되는 주요 단어들인 “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, 그리고 “OPTIONAL”는 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)에 기술된 그대로 해석해야 합니다. 1. 모든 커밋은 `feat`, `fix` 같은 명사로 된 접두어를 포함해야 하고 그 뒤로 옵션인 적용 범위, 그리고 필수인 `:`과 공백이 있어야 합니다. 1. `feat` 타입은 커밋에 애플리케이션이나 라이브러리에 새로운 기능이 추가될 때 사용되어야 합니다. 1. `fix` 타입은 커밋에 애플리케이션의 버그 수정을 하는 내용을 포함하는 경우에 사용되어야 합니다. 1. 적용 범위는 타입 다음에 기술하는데 이는 코드베이스가 적용되는 영역을 기술하는 명사로 괄호로 감싸져야 합니다, 예를 들어, `fix(parser):` 1. 설명은 타입/적용 범위 접두어 뒤에 있는 공백 다음에 작성되어야 합니다. 설명은 코드 변경 사항에 대한 짧은 요약입니다, 예를 들어, _fix: array parsing issue when multiple spaces were contained in string._ 1. 긴 커밋 본문은 짧은 설명 다음에 위치하는데 코드 변경 사항에 대한 추가적인 문맥적인 정보를 제공합니다. 본문은 반드시 설명 다음에 빈 행으로 시작해야 합니다. 1. 한 줄 이상을 가진 꼬리말은 본문 다음 빈 행 다음에 위치합니다. 꼬리말은 커밋에 대한 메타 정보를 포함해야 합니다. 예를 들어, 한 줄에 하나의 메타 정보로 관련 있는 PR, 리뷰어, BREAKING CHANGES를 포함합니다. 1. Breaking changes는 본문 영역의 시작이나 꼬리말 영역의 시작 부분에 위치합니다. Breaking changes는 대문자로 된 BREAKING CHANGE 문자열을 포함하고 그 뒤로 콜론과 공백이 옵니다. 1. 설명은 반드시 `BREAKING CHANGE: ` 다음에 와야 하는데 이는 API에서 변경된 사항을 기술해야 합니다, 예를 들어, _BREAKING CHANGE: environment variables now take precedence over config files._ 1. `feat`와 `fix` 이외의 타입이 커밋 메세지에 사용될 수 있습니다. 1. Conventional Commit을 구성하는 정보의 단위는 반드시 문자이어야 하는 BREAKING CHANGES를 제외하고 구현자에 의해 대소문자를 구분하는 것으로 처리되어서는 안됩니다. 1. `!`는 타입/적용 범위 접두어에서 `:` 앞에 붙어야 하는데 큰 변화에 대한 주의를 주기 위함입니다. `BREAKING CHANGE: description`는 반드시 접두어에 `!`와 함께 본문이나 꼬리말에 포함되어야 합니다. ## 왜 Conventional Commits를 사용할까요? * CHANGELOG를 자동으로 생성하기 위해서 * (포함된 커밋의 타입에 기반하여) 유의적 버전을 자동으로 변경하기 위해서 * 팀 동료, 타인, 그리고 기타 이해당사자에게 변화의 본질을 전달하기 위해서 * 빌드와 배포 프로세스를 수행하기 위해서 * 더 구조화된 커밋 히스토리를 보여줘서 사람들이 프로젝트에 기여하기 더 쉽도록 하기 위해서 ## FAQ ### 초기 개발 단계에서 커밋 메세지를 어떻게 다루어야 하나요? 제품을 이미 출시한 것처럼 진행하세요. 일반적으로 *누군가* 는 여러분의 소프트웨어를 사용하고 있는데 그게 동료 개발자일 수도 있고 그들은 무엇이 고쳐졌는지, 무엇이 문제인지 등을 알고 싶어 할 것입니다. ### 커밋 제목에서 타입은 대문자로 쓰나요 소문자로 쓰나요? 대소문자 구분은 없지만 일관되게 사용하는 것이 좋습니다. ### 커밋이 커밋 타입 중 하나 이상에 해당하는 경우 어떻게 해야 하나요? 가능하면 돌아가서 여러 개의 커밋으로 쪼개세요. Conventional Commits의 이점 중 하나는 우리가 보다 조직화된 커밋과 PR을 만들도록 유도하는 능력입니다. ### Conventional Commits가 빠른 개발과 빠른 반복을 방해하지 않나요? Conventional Commits는 무질서한 방법으로 빨리 움직이는 것을 지양하고 다양한 기여자들을 가진 여러 프로젝트에서 장기적으로 빠르게 이동할 수 있도록 도와줍니다. ### Conventional Commits가 개발자들로 하여금 제공된 타입안에서 생각하게 되기 때문에 그들이 만든 커밋의 타입을 제한하도록 유도할 수 있을까요? Conventional Commits는 fix 같은 특정 종류의 커밋 타입을 더 많이 만들도록 장려하고 있습니다. 그 외에도, Conventional Commits의 유연성은 여러분의 팀이 그들만의 타입을 고안하고 시간이 지남에 따라 그 타입을 바꿀 수 있게 해줍니다. ### 이것이 SemVer와 어떤 관련이 있나요? `fix` 타입의 커밋은 PATCH 버전으로 번역해야 합니다. `feat` 형식 커밋은 MINOR 버전으로 번역해야 합니다. 타입과 관계없이 BREAKING CHANGE를 포함한 커밋은 MAJOR(MAJOR)로 번역해야 한다. ### Conventional Commit 스펙을 개인적으로 확장한 형태의 버전을 어떻게 사용할 수 있을까요? 예를 들어, `@jameswomack/conventional-commit-spec` SemVer를 사용해서 이 규격에 대한 사용자 자신의 확장판을 릴리즈할 것을 추천하며, 이러한 확장하여 사용하는 것을 권장합니다! ### 실수로 잘못된 커밋 타입을 사용하면 어떻게 해야 하나요? #### 스펙에 맞는 타입을 사용하고 있지만 올바른 타입이 아닌 경우, 예를 들어, `feat` 대신 `fix` 실수를 병합 또는 리베이스하기 전에, `git rebase -i`를 사용하여 커밋 히스토리를 편집할 것을 권장합니다. 릴리즈 후에는 사용하는 툴과 프로세스에 따라 정리하는 방법이 다를 수 있습니다. #### 스펙에 맞지 않은 타입을 사용하는 경우, 예를 들어, `feat` 대신 `feet` 최악의 경우, Conventional Commit 규격을 충족하지 않는 커밋이 추가되었다고 해서 그것이 세계의 종말을 의미하지 않습니다. 이는 커밋이 단순히 규격을 기반으로 하는 툴에 의해 누락된다는 것을 의미합니다. ### 모든 기여자가 Conventional Commit 규격을 사용해야 하나요? 아니요! Git을 기반으로 스쿼시를 사용하는 경우, 리드 유지관리자는 커밋된 메시지를 병합할 때 정리할 수 있으므로 일반 커밋자에 작업량이 추가되지 않습니다. 이에 대한 일반적인 작업 흐름은 Git 시스템이 자동으로 풀 요청에서 커밋되도록 하고 리드 유지관리자가 병합에 대한 적절한 Git 커밋 메시지를 입력할 수 있는 양식을 제시하도록 하는 것입니다. ================================================ FILE: content/v1.0.0-beta.4/index.md ================================================ --- draft: false aliases: ["/en/"] --- # Conventional Commits 1.0.0-beta.4 ## Summary The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](http://semver.org), by describing the features, fixes, and breaking changes made in commit messages. The commit message should be structured as follows: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
The commit contains the following structural elements, to communicate intent to the consumers of your library: 1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in semantic versioning). 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning). 1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning). A BREAKING CHANGE can be part of commits of any _type_. 1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. We also recommend `improvement` for commits that improve a current implementation without adding a new feature or fixing a bug. Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`. ## Examples ### Commit message with description and breaking change in body ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Commit message with optional `!` to draw attention to breaking change ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### Commit message with no body ``` docs: correct spelling of CHANGELOG ``` ### Commit message with scope ``` feat(lang): add polish language ``` ### Commit message for a fix using an (optional) issue number. ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by an OPTIONAL scope, and a REQUIRED terminal colon and space. 1. The type `feat` MUST be used when a commit adds a new feature to your application or library. 1. The type `fix` MUST be used when a commit represents a bug fix for your application. 1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., `fix(parser):` 1. A description MUST immediately follow the space after the type/scope prefix. The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string._ 1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. 1. A footer of one or more lines MAY be provided one blank line after the body. The footer MUST contain meta-information about the commit, e.g., related pull-requests, reviewers, breaking changes, with one piece of meta-information per-line. 1. Breaking changes MUST be indicated at the very beginning of the body section, or at the beginning of a line in the footer section. A breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon and a space. 1. A description MUST be provided after the `BREAKING CHANGE: `, describing what has changed about the API, e.g., _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Types other than `feat` and `fix` MAY be used in your commit messages. 1. The units of information that make up conventional commits MUST NOT be treated as case-sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase. 1. A `!` MAY be appended prior to the `:` in the type/scope prefix, to further draw attention to breaking changes. `BREAKING CHANGE: description` MUST also be included in the body or footer, along with the `!` in the prefix. ## Why Use Conventional Commits * Automatically generating CHANGELOGs. * Automatically determining a semantic version bump (based on the types of commits landed). * Communicating the nature of changes to teammates, the public, and other stakeholders. * Triggering build and publish processes. * Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history. ## FAQ ### How should I deal with commit messages in the initial development phase? We recommend that you proceed as if you've already released the product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. ### Are the types in the commit title uppercase or lowercase? Any casing may be used, but it's best to be consistent. ### What do I do if the commit conforms to more than one of the commit types? Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. ### Doesn’t this discourage rapid development and fast iteration? It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors. ### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided? Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time. ### How does this relate to SemVer? `fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases. ### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions!) ### What do I do if I accidentally use the wrong commit type? #### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat` Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use. #### When you used a type *not* of the spec, e.g. `feet` instead of `feat` In a worst case scenario, it's not the end of the world if a commit lands that does not meet the conventional commit specification. It simply means that commit will be missed by tools that are based on the spec. ### Do all my contributors need to use the conventional commit specification? No! If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge. ================================================ FILE: content/v1.0.0-beta.4/index.pt-br.md ================================================ --- draft: false aliases: ["/pt-br/"] --- # Conventional Commits 1.0.0-beta.4 ## Resumo A especificação do Conventional Commits é uma convenção simples para utilizar nas mensagens de commit. Ela define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas. Esta convenção segue o [SemVer](https://semver.org), descrevendo os recursos, correções e modificações que quebram a compatibilidade nas mensagens de commit. A mensagem do commit deve ser estruturada da seguinte forma: --- ``` [escopo opcional]: [corpo opcional] [rodapé opcional] ``` ---
O commit contém os seguintes elementos estruturais, para comunicar a intenção ao utilizador da sua biblioteca: 1. **fix:** um commit do _tipo_ `fix` soluciona um problema na sua base de código (isso se correlaciona com [`PATCH`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). 1. **feat:** um commit do _tipo_ `feat` inclui um novo recurso na sua base de código (isso se correlaciona com [`MINOR`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). 1. **BREAKING CHANGE:** um commit que contém o texto `BREAKING CHANGE:`, no começo do texto do corpo opcional ou do rodapé opcional, inclui uma modificação que quebra a compatibilidade da API (isso se correlaciona com [`MAJOR`](https://semver.org/lang/pt-BR/#sum%C3%A1rio) do versionamento semântico). Uma BREAKING CHANGE pode fazer parte de commits de qualquer _tipo_. 1. Outros: _tipos_ adicionais são permitidos além de `fix:` e `feat:`, por exemplo [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (baseado na [Convenção do Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) recomenda-se `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, entre outros. Também recomendamos `improvement` para commits que melhoram uma implementação atual sem adicionar um novo recurso ou consertar um bug. Observe que esses tipos não são obrigatórios pela especificação do Conventional Commits e não têm efeito implícito no versionamento semântico (a menos que incluam uma BREAKING CHANGE).
Um escopo pode ser adicionado ao tipo do commit, para fornecer informações contextuais adicionais e está contido entre parênteses, por exemplo `feat(parser): adiciona capacidade de interpretar arrays`. ## Exemplos ### Mensagem de commit com descrição e modificação que quebra a compatibilidade no corpo ``` feat: permitir que o objeto de configuração fornecido estenda outras configurações BREAKING CHANGE: a chave `extends`, no arquivo de configuração, agora é utilizada para estender outro arquivo de configuração ``` ### Mensagem de commit com `!` opcional para chamar a atenção para quebra a compatibilidade ``` chore!: remove Node 6 da matriz de testes BREAKING CHANGE: removendo Node 6 que atinge o final de vida em Abril ``` ### Mensagem de commit sem corpo ``` docs: ortografia correta de CHANGELOG ``` ### Mensagem de commit com escopo ``` feat(lang): adiciona tradução para português brasileiro ``` ### Mensagem de commit de uma correção utilizando número de ticket (opcional) ``` fix: corrige pequenos erros de digitação no código veja o ticket para detalhes sobre os erros de digitação corrigidos closes issue #12 ``` ## Especificação As palavras-chaves “DEVE” (“MUST”), “NÃO DEVE” (“MUST NOT”), “OBRIGATÓRIO” (“REQUIRED”), “DEVERÁ” (“SHALL”), “NÃO DEVERÁ” (“SHALL NOT”), “PODEM” (“SHOULD"), “NÃO PODEM” (“SHOULD NOT”), “RECOMENDADO” (“RECOMMENDED”), “PODE” (“MAY”) e “OPCIONAL” (“OPTIONAL”), nesse documento, devem ser interpretados como descrito na [RFC 2119](http://tools.ietf.org/html/rfc2119). 1. A mensagem de commit DEVE ser prefixado com um tipo, que consiste em um substantivo, `feat`,` fix`, etc., seguido por um escopo OPCIONAL, e OBRIGATÓRIO terminar com dois-pontos e um espaço. 1. O tipo `feat` DEVE ser usado quando um commit adiciona um novo recurso ao seu aplicativo ou biblioteca. 1. O tipo `fix` DEVE ser usado quando um commit representa a correção de um problema em seu aplicativo ou biblioteca. 1. Um escopo PODE ser fornecido após um tipo. Um escopo DEVE consistir em um substantivo que descreve uma seção da base de código entre parênteses, por exemplo, `fix(parser): ` 1. Uma descrição DEVE existir depois do espaço após o prefixo tipo/escopo. A descrição é um breve resumo das alterações de código, por exemplo, _fix: problema na interpretação do array quando uma string tem vários espaços._ 1. Um corpo de mensagem de commit mais longo PODE ser fornecido após a descrição curta, fornecendo informações contextuais adicionais sobre as alterações no código. O corpo DEVE começar depois de uma linha em branco após a descrição. 1. Um rodapé de uma ou mais linhas PODE ser fornecido depois de uma linha em branco após o corpo. O rodapé DEVE conter informações adicionais sobre o commit, por exemplo, pull-requests, revisores, modificações que quebram a compatibilidade, com uma informação adicional por linha. 1. A modificação que quebra a compatibilidade DEVE ser indicadas logo no início da seção do corpo ou no início de uma linha na seção de rodapé. Uma modificação que quebra a compatibilidade DEVE consistir de um texto em maiúsculas BREAKING CHANGE, seguido por dois-pontos e um espaço. 1. Uma descrição DEVE ser fornecida após o texto "BREAKING CHANGE:", descrevendo o que mudou na API, por exemplo, _BREAKING CHANGE: as variáveis de ambiente agora têm preferência sobre os arquivos de configuração._ 1. Além de `feat` e `fix`, outro tipo PODE ser usados em suas mensagens de commit. 1. Cada bloco de informação que compõem o commit convencional NÃO DEVE ser tratado como sensível a maiúscula e minúscula pelos implementadores, com exceção de BREAKING CHANGE, que DEVE ser maiúscula. 1. Um `!` PODE ser acrescentado antes do `:` no prefixo tipo/escopo, para chamar a atenção para modificações que quebram a compatibilidade. `BREAKING CHANGE: description` também DEVE ser incluído no corpo ou no rodapé, junto com o `!` no prefixo. ## Porque utilizar Conventional Commits * Criação automatizada de CHANGELOGs. * Determinar automaticamente um aumento de versionamento semântico (com base nos tipos de commits). * Comunicar a natureza das mudanças para colegas de equipe, o público e outras partes interessadas. * Disparar processos de build e deploy. * Facilitar a contribuição de outras pessoas em seus projetos, permitindo que eles explorem um histórico de commits mais estruturado. ## Perguntas Frequentes ### Como devo lidar com mensagens de commit na fase inicial de desenvolvimento? Recomendamos que você proceda como se já tivesse lançado o produto. Normalmente *alguém*, mesmo que seja seus colegas desenvolvedores, está usando seu software. Eles vão querer saber o que foi corrigido, o que quebra etc. ### Os tipos no título das mensagens commit são maiúsculos ou minúsculos? Qualquer opção pode ser usada, mas é melhor ser consistente. ### O que eu faço se o commit estiver de acordo com mais de um dos tipos? Volte e faça vários commits sempre que possível. Parte do benefício do Conventional Commits é a capacidade de nos levar a fazer commits e PRs mais organizados. ### Isso não desencoraja o desenvolvimento rápido e a iteração rápida? Desencoraja a movimentação rápida de forma desorganizada. Ele ajuda você a ser capaz de se mover rapidamente a longo prazo em vários projetos com vários colaboradores. ### O Conventional Commits leva os desenvolvedores a limitar o tipo de commits que eles fazem porque estarão pensando nos tipos fornecidos? O Conventional Commits nos encorajam a fazer mais commits de tipos específicos, por exemplo correções. Além disso, a flexibilidade do Conventional Commits permite que sua equipe crie seus próprios tipos e altere ao longo do tempo. ### Qual a relação com o SemVer? Commits do tipo `fix` devem ser enviados para releases `PATCH`. Commits do tipo `feat` devem ser enviados para releases `MINOR`. Commits com `BREAKING CHANGE` nas mensagens, independentemente do tipo, devem ser enviados para releases `MAJOR`. ### Como devo versionar minhas extensões utilizando a especificação do Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`? Recomendamos utilizar o [SemVer](http://semver.org) para liberar suas próprias extensões para esta especificação (e incentivamos você criar essas extensões!) ### O que eu faço se acidentalmente usar o tipo errado de commit? #### Quando você usou um tipo da especificação, mas não do tipo correto, por exemplo `fix` em vez de `feat` Antes do merge ou relase com o erro, recomendamos o uso de `git rebase -i` para editar o histórico do commit. Após o release, a limpeza será diferente de acordo com as ferramentas e processos que você utiliza. #### Quando você usou um tipo que *não* é da especificação, por exemplo `feet` em vez de `feat` Na pior das hipóteses, não é o fim do mundo se um commit não atender à especificação do Conventional Commits. Significa apenas que o commit será ignorado por ferramentas baseadas nessa especificação. ### Todos os meus colaboradores precisam usar a especificação do Conventional Commits? Não! Se você usar um workflow de git baseado em squash, os mantenedores poderão limpar as mensagens de commit à medida que forem fazendo novos merges, não adicionando carga de trabalho aos committers casuais. Um workflow comum para isso é fazer com que o git faça squash dos commits automaticamente de um pull request e apresente um formulário para o mantenedor inserir a mensagem do commit apropriada para o merge. ================================================ FILE: content/v1.0.0-beta.4/index.ru.md ================================================ --- draft: false aliases: ["/ru/"] --- # Conventional Commits 1.0.0-beta.4 ## Главное Conventional Commits - это простое соглашение о том, как нужно писать сообщения commit'ов. Оно описывает простой набор правил для создания понятной истории commit'ов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории commit'ов. Данное соглашение совместимо с [SemVer](http://semver.org), описывая новые функции (features), исправления (fixes) и изменения, нарушающие обратную совместимость (breaking changes) в сообщениях commit'ов. Сообщения commit'ов должны быть следующей структуры: --- ``` [optional scope]: [optional body] [optional footer] ``` ---
Commit'ы могут содержать следующие структурные элементы для сообщений пользователям вашей библиотеки: 1. **fix:** commit _типа_ `fix` исправляет ошибку (bug) в вашем коде (он соответствует [`PATCH`](http://semver.org/#summary) в SemVer) 1. **feat:** commit _типа_ `feat` добавляет новую функцию (feature) в ваш код (он соответствует [`MINOR`](http://semver.org/#summary) в SemVer). 1. **BREAKING CHANGE:** commit, который содержит текст `BREAKING CHANGE:` в начале своего не обязательного тела сообщения (body) или в подвале (footer), добавляет изменения, нарушающие обратную совместимость вашего API (он соответствует [`MAJOR`](http://semver.org/#summary) в SemVer). BREAKING CHANGE может быть частью commit'а любого _типа_. 1. Другое: commit'ы с _типами_, которые отличаются от `fix:` и `feat:`, также разрешены. Например, [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (основанный на [The Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) рекомендует: `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, и другие. Мы также рекомендуем `improvement` для commit'ов, которые вносят улучшения в текущую реализацию без добавления новых функций и исправления ошибок. Обратите внимание, что данный тип не описывается данной спецификацией и не имеет эффекта в SemVer (за исключением, когда он включает BREAKING CHANGE).
Контекст (scope) может быть объявлен рядом с типом commit'а для добавления дополнительной информации о контексте. Он должен содержаться в круглых скобках, например, `feat(parser): add ability to parse arrays`. ## Примеры ### Сообщение commit'а с описанием и изменениям, нарушающим обратную совместимость, в теле ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### Сообщение commit'a с не обязательным `!`, для того, чтобы привлечь внимание к изменениям, нарушающим обратную совместимость ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### Сообщение commit'а без тела ``` docs: correct spelling of CHANGELOG ``` ### Сообщение commit'а с указанием контекста (scope) ``` feat(lang): add polish language ``` ### Сообщение commit'а, исправляющего ошибку (fix), использующее не обязательный номер задачи (issue) в багтрекере ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## Спецификация Слова “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, и “OPTIONAL” в данном документе должны интерпретироваться как в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). 1. Commit'ы должны (MUST) начинаться с типа, который является существительным: `feat`, `fix`, и т.д., за которым следуют не обязательное (OPTIONAL) указание контекста (scope), двоеточие и пробел. 1. Тип `feat` должен (MUST) использоваться, когда commit добавляет новый функционал (feature) в ваше приложение или библиотеку. 1. Тип `fix` должен (MUST) использоваться, когда commit исправляет ошибку (fix) в вашем приложении или библиотеке. 1. Контекст (scope) может (MAY) следовать после типа. Контекст должен (MUST) быть существительным, заключенным в круглые скобки, описывающий часть кодовой базы, которую затронул commit. Например, `fix(parser):`. 1. Описание должно (MUST) следовать через пробел сразу же после типа/контекста. Описание - это краткая выжимка об изменениях кода, например, _fix: array parsing issue when multiple spaces were contained in string._ 1. Тело (body) commit'а может (MAY) следовать после короткого описания, добавляя дополнительную информацию об изменениях в коде. Тело должно (MUST) отделяться от короткого описания одной пустой строкой. 1. Подвал (footer) может (MAY) быть представлен одной или несколькими строками после тела commit'а. Он должен быть отделен от тела commit'а одной пустой строкой. Подвал должен (MUST) содержать мета-информацию о commit'е. Например, связанные pull-request'ы, обсуждения, изменения, нарушающие обратную совместимость. По одной мета-информации на строку. 1. Изменения, нарушающие обратную совместимость (breaking changes), должны (MUST) быть указаны в самом начале тела (body) или в начале одной из строк подвала (footer). Изменения, нарушающие обратную совместимость, должны (MUST) начинаться с текста, написанного прописными буквами, BREAKING CHANGE, за которым должны следовать двоеточие и пробел. 1. Описание изменений, нарушающих обратную совместимость, должно (MUST) следовать после `BREAKING CHANGE: `. В нем должно содержаться то, что изменилось в API. Например, _BREAKING CHANGE: environment variables now take precedence over config files._ 1. Типы отличные от `feat` и `fix` могут (MAY) быть использованы в ваших commit'ах. 1. Единицы информации, которые составляют обычные commit'ы, не должны (MUST NOT) трактоваться разработчиками как регистрозависимые, за исключением BREAKING CHANGE, который всегда должен быть написан прописными буквами. 1. Знак `!` может (MAY) быть добавлен перед `:` в тип/контекст, чтоб обратить внимание на изменения. Строка `BREAKING CHANGE: description` должна (MUST) быть добавлена в тело (body) или подвал (footer), если используется `!` в префиксе. ## Почему нужно использовать Conventional Commits * Автоматически генерируемый CHANGELOGs. * Автоматическое определение семантической версии SemVer (на основе типов совершенных commit'ов). * Коммуникация о характере изменений между товарищами по команде, общественностью и другими заинтересованными сторонами. * Автоматически срабатываемый процесс сборки и публикации. * Людям проще участвовать в вашем проекте, потому что им доступна более структурированная история коммитов. ## FAQ ### Как я должен писать сообщения commit'ов на начальной стадии разработки? Мы рекомендуем писать сообщения commit'ов так, как будто вы уже выпустили продукт. Как правило, *кто-то*, например, ваши коллеги, уже используют ваш код. И они хотят знать, что исправилось, что изменилось, какие нарушения обратной совместимости появились и т.д. ### В каком регистре я должен писать заголовки commit'ов? Любой регистр можно использовать, но лучше во всей истории использовать один стиль. ### Что мне делать, если commit должен содержать больше одного типа? Вернитесь назад и сделайте несколько commit'ов, если это возможно. Часть из преимуществ использования Conventional Commits - это его способность побуждать делать более организованные коммиты и PR'ы. ### Разве это не препятствует быстрому развитию и быстрой интеграции? Это препятствует быстрому развитию в неорганизованном виде. Это помогает быстро двигаться в проектах с несколькими участниками. ### Могут ли Conventional Commits заставить разработчиков ограничивать их типы commit'ов, потому что им придется думать об этих типах? Conventional Commits побуждают делать больше commit'ов с определенными типами, такими как `fix`. Кроме того, гибкость Conventional Commits позволяет вашей команде создавать свои собственные типы и изменять их с течением времени. ### Как это связано с правилами семантического управления версиями [SemVer](http://semver.org)? `fix` тип commit'а должен быть отражен в `PATCH`-релизе. `feat` тип commit'а должен быть отражен в `MINOR`-релизе. Commit'ы с `BREAKING CHANGE` в теле или подвале, независимо от типа, должны быть отражены в `MAJOR`-релизе. ### Как я должен версионировать мои расширения к спецификации Conventional Commits, например, `@jameswomack/conventional-commit-spec`? Мы рекомендуем использовать [SemVer](http://semver.org) для релизов ваших расширений к этой спецификации (и рекомендуем делать эти расширения!). ### Что мне делать, если я случайно использовал не тот тип commit'а? #### Что если вы использовали тип, который имеет спецификацию, но это неправильный тип. Например, `fix` вместо `feat` Перед слиянием или релизом ошибки, мы рекомендуем использовать `git rebase -i` для редактирования истории commit'ов. После `release`, исправления будут отличаться в зависимости от того, какие инструменты вы используете. #### Когда вы использовали тип, *не* описанный спецификацией, например, `feet` вместо `feat` Это не конец света, это просто обозначает, что коммит будет упущен при работе утилит, основанных на спецификации. ### Должны ли все мои соавторы использовать спецификацию Conventional Commit? Нет! Если ваш рабочий процесс основан на использовании слияния (squash) Git, сопровождающий проекта может очистить историю всех предыдущих commit'ов при их слиянии, не добавляя рабочей нагрузки на случайные commit'ы. Обычно, рабочий процесс строится на том, что ваша система Git автоматически объединяет (squash) все предыдущие commit'ы перед pull-запросом и предоставляет форму сопровождающему проекта для ввода нового commit'а. ================================================ FILE: content/v1.0.0-beta.4/index.zh-hans.md ================================================ --- draft: false aliases: ["/zh/", "/zh-hans/"] --- # 约定式提交 1.0.0-beta.4 ## 概述 约定式提交规范是一种基于提交消息的轻量级约定。 它提供了一组用于创建清晰的提交历史的简单规则； 这使得编写基于规范的自动化工具变得更容易。 这个约定与 [SemVer](http://semver.org) 相吻合， 在提交信息中描述新特性、bug 修复和破坏性变更。 提交说明的结构如下所示： --- ``` <类型>[可选的作用域]: <描述> [可选的正文] [可选的脚注] ``` ---
提交说明包含了下面的结构化元素，以向类库使用者表明其意图： 1. **fix:** _类型_ 为 `fix` 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 [`PATCH`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 2. **feat:** _类型_ 为 `feat` 的提交表示在代码库中新增了一个功能（这和语义化版本中的 [`MINOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 3. **BREAKING CHANGE:** 在可选的正文或脚注的起始位置带有 `BREAKING CHANGE:` 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 [`MAJOR`](https://semver.org/lang/zh-CN/#%E6%91%98%E8%A6%81) 相对应）。 破坏性变更可以是任意 _类型_ 提交的一部分。 1. **其它情况:** 除 `fix:` 和 `feat:` 之外的提交 _类型_ 也是被允许的，例如 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)（基于 [Angular 约定](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)）中推荐的 `chore:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` 及其他标签。 我们也推荐使用`improvement`，用于对当前实现进行改进而没有添加新功能或修复错误的提交。 请注意，这些标签在约定式提交规范中并不是强制性的。并且在语义化版本中没有隐式的影响（除非他们包含 BREAKING CHANGE）。
可以为提交类型添加一个围在圆括号内的作用域，以为其提供额外的上下文信息。例如 `feat(parser): adds ability to parse arrays.`。 ## 示例 ### 包含了描述以及正文内有破坏性变更的提交说明 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 包含了可选的 `!` 字符以提醒注意破坏性变更的提交说明 ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### 不包含正文的提交说明 ``` docs: correct spelling of CHANGELOG ``` ### 包含作用域的提交说明 ``` feat(lang): add polish language ``` ### 为 fix 编写的提交说明，包含（可选的） issue 编号 ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## 约定式提交规范 本文中的关键词 “必须（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）” ，解释参考 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 中所述。 1. 每个提交都**必须**使用类型字段前缀，它由一个名词组成，诸如 `feat` 或 `fix` ，其后接一个**可选的**作用域字段，以及一个**必要的**冒号（英文半角）和空格。 1. 当一个提交为应用或类库实现了新特性时，**必须**使用 `feat` 类型。 1. 当一个提交为应用修复了 bug 时，**必须**使用 `fix` 类型。 1. 作用域字段**可以**跟随在类型字段后面。作用域**必须**是一个描述某部分代码的名词，并用圆括号包围，例如： `fix(parser):` 1. 描述字段**必须**紧接在类型/作用域前缀的空格之后。描述指的是对代码变更的简短总结，例如： _fix: array parsing issue when multiple spaces were contained in string._ 1. 在简短描述之后，**可以**编写更长的提交正文，为代码变更提供额外的上下文信息。正文**必须**起始于描述字段结束的一个空行后。 1. 在正文结束的一个空行之后，**可以**编写一行或多行脚注。脚注**必须**包含关于提交的元信息，例如：关联的合并请求、Reviewer、破坏性变更，每条元信息一行。 1. 破坏性变更**必须**标示在正文区域最开始处，或脚注区域中某一行的开始。一个破坏性变更**必须**包含大写的文本 `BREAKING CHANGE`，后面紧跟冒号和空格。 1. 在 `BREAKING CHANGE: ` 之后**必须**提供描述，以描述对 API 的变更。例如： _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 在提交说明中，**可以**使用 `feat` 和 `fix` 之外的类型。 1. 工具的实现**必须不**区分大小写地解析构成约定式提交的信息单元，只有 `BREAKING CHANGE` **必须**是大写的。 1. **可以**在类型/作用域前缀之后，`:` 之前，附加 `!` 字符，以进一步提醒注意破坏性变更。当有 `!` 前缀时，正文或脚注内**必须**包含 `BREAKING CHANGE: description` ## 为什么使用约定式提交 * 自动化生成 CHANGELOG。 * 基于提交的类型，自动决定语义化的版本变更。 * 向同事、公众与其他利益关系者传达变化的性质。 * 触发构建和部署流程。 * 让人们探索一个更加结构化的提交历史，以便降低对你的项目做出贡献的难度。 ## FAQ ### 在初始开发阶段我该如何处理提交说明？ 我们建议你按照假设你已发布了产品那样来处理。因为通常总 *有人* 使用你的软件，即便那是你软件开发的同事们。他们会希望知道诸如修复了什么、哪里不兼容等信息。 ### 提交标题中的类型是大写还是小写? 大小写都可以，但最好是一致的。 ### 如果提交符合多种类型我该如何操作？ 回退并尽可能创建多次提交。约定式提交的好处之一是能够促使我们做出更有组织的提交和 PR。 ### 这不会阻碍快速开发和迭代吗？ 它阻碍的是以杂乱无章的方式快速前进。它助你能在横跨多个项目以及和多个贡献者协作时长期地快速演进。 ### 约定式提交会让开发者受限于提交的类型吗（因为他们会想着已提供的类型）？ 约定式提交鼓励我们更多地使用某些类型的提交，比如 `fixes`。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。 ### 这和 SemVer 有什么关联呢？ `fix` 类型提交应当对应到 `PATCH` 版本。`feat` 类型提交应该对应到 `MINOR` 版本。带有 `BREAKING CHANGE` 的提交不管类型如何，都应该对应到 `MAJOR` 版本。 ### 我对约定式提交做了形如 `@jameswomack/conventional-commit-spec` 的扩展，该如何版本化管理这些扩展呢？ 我们推荐使用 SemVer 来发布你对于这个规范的扩展（并鼓励你创建这些扩展！） ### 如果我不小心使用了错误的提交类型，该怎么办呢？ #### 当你使用了在规范中但错误的类型时，例如将 `feat` 写成了 `fix` 在合并或发布这个错误之前，我们建议使用 `git rebase -i` 来编辑提交历史。而在发布之后，根据你使用的工具和流程不同，会有不同的清理方案。 #### 当使用了 *不* 在规范中的类型时，例如将 `feat` 写成了 `feet` 在最坏的场景下，即便提交没有满足约定式提交的规范，也不会是世界末日。这只意味着这个提交会被基于规范的工具错过而已。 ### 所有的贡献者都需要使用约定式提交规范吗？ 并不！如果你使用基于 squash 的 Git 工作流，主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。 有种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交，并向主管维护者提供一份表单，用以在合并时输入合适的 git 提交信息。 ================================================ FILE: content/v1.0.0-beta.4/index.zh-hant.md ================================================ --- draft: false aliases: ["/zh-hant/"] --- # 慣例式提交 1.0.0-beta.4 ## 概述 慣例式提交規範，是一種對提交說明的輕量慣例。 它提供一些簡單的條件集合用於建立明確的提交歷史； 這能讓自動化工具更容易撰寫。 這份慣例能對應到 [SemVer](https://semver.org/lang/zh-TW/)， 透過在提交說明裡描述功能、修正以及重大變更。 提交說明應被以下方式建構： --- ``` <類型>[可選的作用範圍]: <描述> [可選的正文] [可選的頁腳] ``` ---
提交應包含以下結構性元素，用以向使用這套函式庫的使用者溝通當時的意圖： 1. **fix:** 為 `fix` _類型_ 的提交，表示對程式修正了一個臭蟲 (對應到語意化版本中的 [`PATCH`](http://semver.org/#summary))。 1. **feat:** 為 `feat` _類型_ 的提交，表示對程式增加了一個功能 (對應到語意化版本中的 [`MINOR`](http://semver.org/#summary))。 1. **BREAKING CHANGE:** 在可選的正文或是頁腳的起始文字為 `BREAKING CHANGE:` 的提交，表示有重大的 API 變更 (對應到語意化版本中的 [`MAJOR`](http://semver.org/#summary))。 重大變更可以是任何 _類型_ 提交的一部分。 1. 其他: 除 `fix:` 與 `feat:` 以外，其他的提交 _類型_ 也是被允許的，例如 [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (基於 [Angular 慣例](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)) 中推薦的 `chore:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` 以及更多。 我們也推薦對那些沒有增加新功能或是修正臭蟲而是改善目前實作的提交使用 `improvement`。 請注意，這些類型在慣例式提交規範中並不是強制性的，且在語意化版本中也沒有隱含的作用 (除非它們包含 BREAKING CHANGE)。
提交的類型可以在括號內給予作用範圍，以提供額外的脈絡資訊。例如：`feat(parser): add ability to parse arrays`。 ## 範例 ### 包含描述以及正文有重大變更的提交說明 ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 包含可選的 `!` 用以提示重大變更的提交說明 ``` chore!: drop Node 6 from testing matrix BREAKING CHANGE: dropping Node 6 which hits end of life in April ``` ### 不包含正文的提交說明 ``` docs: correct spelling of CHANGELOG ``` ### 包含作用範圍的提交說明 ``` feat(lang): add polish language ``` ### 為修正而寫提交說明，包含 (可選的) 問題編號 ``` fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12 ``` ## 規範 在本文中使用的關鍵字：必須 (MUST)、禁止 (MUST NOT)、必要 (REQUIRED)、應當 (SHALL)、不應當 (SHALL NOT)、應該 (SHOULD)、不應該 (SHOULD NOT)、推薦 (RECOMMENDED)、可以 (MAY) 以及可選 (OPTIONAL) 應以 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) 為參考解釋。 1. 每個提交最前面**必須**要有類型，類型由名詞組成，例如：`feat`、`fix` 等，後接上**可選的**作用範圍以及**必要的**一個冒號與空格。 1. 當提交一個新功能到你的應用程式或是函式庫時，**必須**使用 `feat` 類型。 1. 當提交一個臭蟲修正到你的應用程式時，**必須**使用 `fix` 類型。 1. 作用範圍**可以**給予在類型之後。一個作用範圍**必須**由一個描述程式區段的名詞所組成，並用括號包覆。例如： `fix(parser):` 1. 描述**必須**緊接在類型/作用範圍的空格之後。描述是一個對程式碼變更的簡短總結，例如： _fix: array parsing issue when multiple spaces were contained in string._ 1. 在簡短的描述後**可以**給予更長的提交正文，對程式碼變更提供額外的脈絡資訊。正文**必須**在描述後的一個空行之後開始。 1. 在正文後**可以**給予一行或是多行的頁腳。頁腳**必須**包含關於提交的詮釋資訊，例如：相關的拉取請求 (pull-request)、審核者、重大變更，每個詮釋資訊一行。 1. 重大變更**必須**在標示在正文區段的最前面，或是標示在頁腳區段的每行最前面。一個重大變更**必須**由大寫的 BREAKING CHANGE 文字所組成，後接一個冒號與空格。 1. `BREAKING CHANGE: ` 之後**必須**提供描述，說明 API 的變更部分。例如： _BREAKING CHANGE: environment variables now take precedence over config files._ 1. 在提交訊息中，**可以**使用 `feat` 與 `fix` 以外的類型。 1. 實作上，慣例式提交的訊息單元**禁止**以區分大小寫的方式解析，只有 BREAKING CHANGE **必須**是大寫。 1. 在類型/作用範圍的 `:` 之前**可以**加上一個 `!`，用以提示重大變更。當有這個提示時，正文或頁腳內**必須**包含 `BREAKING CHANGE: description` 。 ## 為何要使用慣例式提交 * 自動產生 CHANGELOG。 * 基於提交的類型，自動決定語意化版本的升級。 * 向同事、公眾以及其他的利益相關者傳達變化的過程。 * 觸發建置與發布流程。 * 藉由更有結構的提交歷史，有助於你的專案讓其他人參與開發。 ## FAQ ### 在初始的開發階段，我該如何處理提交說明？ 我們建議你可以就像是產品已經發行的那樣去執行。因為通常都會 *有人* 使用你的軟體，即使是你的軟體開發的同事們，他們會希望知道修正了什麼以及有什麼重大變更等資訊。 ### 提交標題中的類型應該要用大寫還是小寫？ 大小寫都可以，但是最好是一致的。 ### 當提交符合一或多種提交類型，我應該怎麼做？ 退回並盡可能切成多個提交。慣例式提交的一個好處就是它能夠促使我們做更有組織的提交與拉取請求 (PR)。 ### 這不會阻礙快速開發與快速迭代嗎？ 它阻礙用非組織化的方式快速前進。它幫助你長期能在橫跨多個專案與多個貢獻者協作時都能快速前進。 ### 慣例式提交會讓開發者受限於提交的類型，因為他們會用已提供的類型去思考嗎？ 慣例式提交鼓勵我們多使用某些類型的提交，例如 `fixes`。除此之外，慣例式提交的彈性也允許你的團隊使用自己的類型，以及隨時間推移更改這些類型。 ### 這與 SemVer 有什麼關係呢？ `fix` 類型的提交應該對應到 `PATCH` 發行版。`feat` 類型的提交應該對應到 `MINOR` 發行版。含有 `BREAKING CHANGE` 的提交，無論是什麼類型，都應該要對應到 `MAJOR` 發行版。 ### 我對慣例式提交做了擴充 (例如：`@jameswomack/conventional-commit-spec`)，我該如何管理這些擴充的版本呢？ 我們推薦使用 SemVer 來發行你對這份規範的擴充 (並且也鼓勵你做些擴充！) ### 如果我不小心用錯提交類型，該怎麼辦？ #### 當你使用規範中但是錯誤的類型，例如：將 `feat` 寫成 `fix` 在合併或是發行這個錯誤之前，我們推薦使用 `git rebase -i` 來編輯提交歷史。 而在發行之後，根據你使用的工具與流程，會有不同的清理方式。 #### 當你使用 *非* 規範中的類型時，例如：將 `feat` 寫成 `feet` 最糟狀況下，即使提交沒有符合慣例式提交的規範，也不會是世界末日。它僅意味著這個提交將會被基於這個規範的工具略過。 ### 所有的貢獻者都需要使用慣例式提交的規範嗎？ 不用！如果你使用的是基於 squash 的 Git 工作流程，主維護者可以在合併時清理提交說明，因此這不會對一般的提交者產生額外的負擔。 有一種常見的工作流程是讓 git 系統自動從 pull request 中 squash 出提交，然後提供一份表單給主維護者，用以在合併的時候輸入合適的 git 提交說明。 ================================================ FILE: data/.gitkeep ================================================ ================================================ FILE: docker-compose.yml ================================================ version: '3' services: app: build: dockerfile: Dockerfile.dev context: . ports: - "1313:1313" working_dir: /src/ volumes: - ./:/src/ ================================================ FILE: layouts/.gitkeep ================================================ ================================================ FILE: static/.gitkeep ================================================ ================================================ FILE: themes/conventional-commits/.editorconfig ================================================ # http://editorconfig.org root = true [*] charset = utf-8 indent_style = space indent_size = 2 end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true [*.md] insert_final_newline = false trim_trailing_whitespace = false ================================================ FILE: themes/conventional-commits/.gitignore ================================================ .idea .DS_Store static/css/index.css static/css/style.css static/css/style.css.map static/css/style.min.css static/js/bundle.js # Logs logs *.log npm-debug.log* yarn-debug.log* yarn-error.log* # Runtime data pids *.pid *.seed *.pid.lock # Directory for instrumented libs generated by jscoverage/JSCover lib-cov # Coverage directory used by tools like istanbul coverage # nyc test coverage .nyc_output # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) .grunt # Bower dependency directory (https://bower.io/) bower_components # node-waf configuration .lock-wscript # Compiled binary addons (https://nodejs.org/api/addons.html) build/Release # Dependency directories node_modules/ jspm_packages/ # TypeScript v1 declaration files typings/ # Optional npm cache directory .npm # Optional eslint cache .eslintcache # Optional REPL history .node_repl_history # Output of 'npm pack' *.tgz # Yarn Integrity file .yarn-integrity # dotenv environment variables file .env ================================================ FILE: themes/conventional-commits/LICENSE ================================================ The MIT License (MIT) Copyright (c) 2018 YOUR_NAME_HERE Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: themes/conventional-commits/README.md ================================================ # hugo conventional commits theme Copy hugo-conventional-commits-theme inside your my-hugo-site/theme ## config.yaml example All config params are optionals. ```yaml baseURL: 'http://conventional-commits.org/' languageCode: en-us title: Conventional Commits theme: conventional-commits # Language defaultContentLanguageInSubdir: true defaultContentLanguage: "en" languages: en: weight: 1 languageName: "English" it: weight: 2 languageName: "Italian" # Content params: versions: current: 1.0.0-beta.2 list: - label: 1.0.0-beta url: 'https://github.com/conventional-commits/conventionalcommits.org' - label: 1.0.0-beta.1 url: 'https://github.com/conventional-commits/conventionalcommits.org' - label: 1.0.0-beta.2 url: 'https://github.com/conventional-commits/conventionalcommits.org' welcome: description: A specification made for write standardized and useful commit messages image: 'https://path-to-image' actions: - label: Read the specs url: 'https://github.com/conventional-commits/conventionalcommits.org' - label: GitHub url: 'https://github.com/conventional-commits/conventionalcommits.org' license: title: License action: label: Creative Commons - CC BY 3.0 url: 'https://creativecommons.org/licenses/by/3.0/' footer: logos: - name: github url: 'https://github.com/conventional-commits/conventionalcommits.org' ``` ## Apply theme changes Development script ```ssh npm run start ``` Production script ```ssh npm run build ``` ## Shortcodes * banner-image * src (optional) | default: static/img/git-flow.png ================================================ FILE: themes/conventional-commits/archetypes/default.md ================================================ +++ +++ ================================================ FILE: themes/conventional-commits/layouts/404.html ================================================
404
================================================ FILE: themes/conventional-commits/layouts/_default/single.html ================================================ {{- partial "head.html" . -}} {{- partial "header.html" . -}} {{- partial "welcome.html" . -}}
{{.Content}}
{{- partial "footer.html" . -}} {{- partial "scripts.html" . -}} ================================================ FILE: themes/conventional-commits/layouts/about/single.html ================================================ {{- partial "head.html" . -}} {{- partial "header.html" . -}} {{- partial "mini_welcome.html" . -}}
{{.Content}}
{{- partial "footer.html" . -}} {{- partial "scripts.html" . -}} ================================================ FILE: themes/conventional-commits/layouts/partials/footer.html ================================================ ================================================ FILE: themes/conventional-commits/layouts/partials/head.html ================================================ {{ .Param "Title" }} ================================================ FILE: themes/conventional-commits/layouts/partials/header.html ================================================
================================================ FILE: themes/conventional-commits/layouts/partials/mini_welcome.html ================================================

{{.Param "Title"}}

{{.Param "Description"}}

================================================ FILE: themes/conventional-commits/layouts/partials/scripts.html ================================================ ================================================ FILE: themes/conventional-commits/layouts/partials/svg-github.html ================================================ ================================================ FILE: themes/conventional-commits/layouts/partials/welcome.html ================================================

{{.Param "Title"}}

{{.Param "Description"}}

{{ if .Param "Actions" }}
{{ range .Param "Actions" }} {{.label}} {{ end }}
{{ end }}
================================================ FILE: themes/conventional-commits/layouts/shortcodes/banner-image.html ================================================ ================================================ FILE: themes/conventional-commits/package.json ================================================ { "name": "hugo-conventional-commits-theme", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "start": "npm run css & npm run css:watch & npm run js:watch", "css": "sass ./static/css/scss/style.scss ./static/css/style.css", "css:watch": "npm run css -- -w", "css:autoprefixer": "postcss --no-map --use autoprefixer -o ./static/css/style.css ./static/css/style.css", "css:nano": "postcss --no-map --use cssnano -o ./static/css/style.css ./static/css/style.css", "css:build": "npm run css && npm run css:autoprefixer && npm run css:nano", "js": "npm run js:bundle -- --mode=development", "js:watch": "npm run js -- --watch", "js:bundle": "webpack ./static/js/index.js -o ./static/js --output-filename bundle.js", "js:build": "npm run js:bundle -- --mode=production", "build": "npm run css:build && npm run js:build" }, "author": "", "license": "MIT", "dependencies": { "anchor-js": "4.3.1", "github-markdown-css": "2.10.0" }, "devDependencies": { "autoprefixer": "10.4.12", "cssnano": "5.1.13", "sass": "1.55.0", "postcss": "8.4.18", "postcss-cli": "10.0.0", "webpack": "5.74.0", "webpack-cli": "4.10.0" } } ================================================ FILE: themes/conventional-commits/static/css/scss/abstracts/_functions.scss ================================================ @import "./../abstracts/variables"; @function get-color-accessible-for-background($color) { @if (lightness( $color ) > 50) { @return darken($color, 60%) } @else { @return lighten($color, 60%) } } ================================================ FILE: themes/conventional-commits/static/css/scss/abstracts/_mixins.scss ================================================ @import "variables"; @mixin up-to-mobile { @media (max-width: #{$mobile-width - 1px}) { @content; } } @mixin tablet { @media (min-width: #{$tablet-width}) and (max-width: #{$desktop-width - 1px}) { @content; } } @mixin desktop { @media (min-width: #{$desktop-width}) { @content; } } @mixin gradient-primary($deg: 45deg) { background: linear-gradient($deg, $color-primary 0%, $color-primary-light 100%); } @mixin dropdown-animation-visible { visibility: visible; opacity: 1; transform: translate(-50%, $dropdown-options-space-from-label); } @mixin dropdown-animation-hidden { visibility: hidden; opacity: 0; transform: translate(-50%, 0); } ================================================ FILE: themes/conventional-commits/static/css/scss/abstracts/_variables.scss ================================================ $color-primary: #FE5196; $color-primary-light: #F77062; $color-neutral-light: #FFF; $color-neutral-dark: #000; $color-primary-heading: #FA6673; $gap-sm: 8px; $gap-md: 24px; $gap-lg: 48px; $radius-md: 4px; $radius-lg: 8px; $shadow-soft: 0 2px 10px 0 rgba(0, 0, 0, .03), 0 2px 20px 10px rgba(0, 0, 0, 0.02); $mobile-width: 350px; $tablet-width: 768px; $desktop-width: 1024px; $header-height: 56px; $footer-logo-size: 24px; $welcome-min-height: 450px; $welcome-height: 100vh; $welcome-action-color: $color-neutral-light; $main-background: $color-neutral-light; $article-background: $color-neutral-light; $article-offset-top: -$header-height + -$gap-sm; $dropdown-border-radius: $radius-md; $dropdown-animation-timing: .4s; $dropdown-label-padding: 12px 8px; $dropdown-label-background-color: transparent; $dropdown-arrow-size: 10px; $dropdown-options-background-color: $color-neutral-light; $dropdown-options-space-from-label: $gap-sm; $dropdown-option-padding: 12px 16px; $dropdown-option-border-bottom-color: rgba($color-neutral-dark, .04); $banner-image-height: 300px; ================================================ FILE: themes/conventional-commits/static/css/scss/abstracts/index.scss ================================================ @import './variables'; @import './mixins'; @import './functions'; ================================================ FILE: themes/conventional-commits/static/css/scss/base/_base.scss ================================================ @import "./../abstracts/index"; * { margin: 0; padding: 0; box-sizing: border-box; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; -webkit-tap-highlight-color: rgba($color-neutral-dark, 0); } body { position: relative; min-height: 100vh; font: 16px Helvetica, sans-serif; } // Apply RTL direction only if 'rtl' class is present html.rtl body, html.rtl .content { direction: rtl; text-align: right; } .container { width: 100%; max-width: $desktop-width; margin-left: auto; margin-right: auto; padding-left: $gap-md; padding-right: $gap-md; } main { background-color: $main-background; } article { background-color: $article-background; transform: translateY($article-offset-top); padding-top: $gap-md; padding-bottom: $gap-md; border-radius: $radius-lg; min-height: 50vh; box-shadow: $shadow-soft; } @include desktop { .container { padding-left: $gap-lg; padding-right: $gap-lg; } article { padding-top: $gap-lg - $gap-sm; padding-bottom: $gap-lg - $gap-sm; } } .no-style-a { text-decoration: none; color: white; } ================================================ FILE: themes/conventional-commits/static/css/scss/components/_banner-image.scss ================================================ @import "./../abstracts/index"; .banner-image { width: 100%; border-radius: $radius-md; margin: $gap-lg 0; box-shadow: $shadow-soft; @include gradient-primary(14deg); img.banner-image__picture { display: block; width: 100%; min-height: 100px; max-height: $banner-image-height; object-fit: contain; margin: auto; background-color: transparent; } } ================================================ FILE: themes/conventional-commits/static/css/scss/components/_dropdown.scss ================================================ @use "sass:math"; @import "./../abstracts/index"; @keyframes show { from { @include dropdown-animation-hidden; } to { @include dropdown-animation-visible; } } @keyframes hide { from { @include dropdown-animation-visible; } to { @include dropdown-animation-hidden; } } .dropdown { position: relative; &__label { display: block; width: 100%; appearance: none; border: none; outline: none; font-size: inherit; color: inherit; text-decoration: inherit; text-transform: inherit; text-align: center; padding: $dropdown-label-padding; background-color: $dropdown-label-background-color; border-radius: $dropdown-border-radius; &:after { display: none; content: ''; width: 100%; height: $dropdown-options-space-from-label * 1.5; position: absolute; top: 100%; left: 0; background-color: transparent; } } &__options { visibility: visible; z-index: 1; min-width: 110px; max-height: 50vh; position: absolute; top: 100%; left: 50%; transform: translate(-50%, 0); list-style: none; font-size: 13px; background-color: $dropdown-options-background-color; border-radius: $dropdown-border-radius; box-shadow: $shadow-soft; overflow: auto; animation: hide math.div($dropdown-animation-timing, 2) ease forwards; @include up-to-mobile { top: 75%; } &:before { content: ''; width: 0; height: 0; position: absolute; top: 0; left: 50%; border-style: solid; border-width: 0 $dropdown-arrow-size math.div($dropdown-arrow-size, 2) $dropdown-arrow-size; border-color: transparent transparent $dropdown-options-background-color transparent; transform: translate(-50%, -100%); } } &__option { a { display: block; padding: $dropdown-option-padding; color: rgba(black, .6); text-decoration: none; border-bottom: 1px solid $dropdown-option-border-bottom-color; transition: background-color .3s ease, color .3s ease; text-transform: none; font-weight: normal; &:hover, &:focus { color: $color-primary; background-color: rgba($color-neutral-dark, .025); } } &:last-child a { border-bottom: none; } } &:hover &__label:after, &:hover &__options, &:focus &__label:after, &:focus &__options { display: block; } &:hover &__options, &:focus &__options { animation: show $dropdown-animation-timing ease forwards; } } ================================================ FILE: themes/conventional-commits/static/css/scss/layout/_footer.scss ================================================ @import "./../abstracts/index"; .footer { margin: ($article-offset-top + ($gap-md*3)) 0 ($gap-md*3); .container { display: flex; align-items: center; } &__license { margin-right: auto; a { font-size: .7em; text-decoration: none; color: inherit; &:hover { text-decoration: underline; } } } &__logos { margin-left: auto; } &__logo { display: flex; } .github { width: $footer-logo-size; height: $footer-logo-size; } } ================================================ FILE: themes/conventional-commits/static/css/scss/layout/_header.scss ================================================ @import "./../abstracts/index"; .header { position: absolute; z-index: 10; top: 12px; left: 0; width: 100%; .container { display: flex; align-items: center; justify-content: space-between; height: $header-height; font-size: .8em; font-weight: bold; text-transform: uppercase; } .logo { width: 30px; height: 30px; background-color: transparent; border: 2px solid #FFF; border-radius: 50%; } &__menu { display: flex; color: $color-neutral-light; list-style: none; margin-left: $gap-sm * 2; } &__menu-item { margin-right: $gap-sm; &:last-child { margin-right: 0; } } } @include up-to-mobile { .header { .container { align-items: flex-start; height: auto; margin-top: $gap-sm; } &__menu { flex-direction: column; justify-content: flex-end; align-items: flex-end; margin-top: $gap-sm * -1; } &__menu-item { margin-right: 0; } } } ================================================ FILE: themes/conventional-commits/static/css/scss/layout/_welcome.scss ================================================ @use "sass:math"; @import "./../abstracts/index"; .welcome { position: relative; z-index: 0; background: $color-primary; @include gradient-primary(); .container { position: relative; z-index: 2; display: flex; flex-direction: column; justify-content: center; height: $welcome-height; min-height: $welcome-min-height; color: $color-neutral-light; } .mini_container { position: relative; z-index: 2; display: flex; flex-direction: column; justify-content: center; min-height: $welcome-min-height; color: $color-neutral-light; width: 100%; max-width: $desktop-width; margin-left: auto; margin-right: auto; padding-left: $gap-md; padding-right: $gap-md; } &__title { font-size: 2.6em; margin-bottom: $gap-sm; @include up-to-mobile { word-break: break-all; } @include desktop { width: 85%; font-size: 3.6em; } } &__description { font-size: 18px; width: 100%; @include desktop { width: 80%; } } &__actions { display: flex; margin-top: math.div($gap-lg * 3, 2); flex-wrap: wrap; } &__action { padding: 12px 16px; border-radius: 50px; text-decoration: none; line-height: 1.5; color: $welcome-action-color; border: 1px solid $welcome-action-color; margin-right: $gap-md; margin-bottom: $gap-md; transition: background-color .3s ease, color .3s ease; min-width: fit-content; &:hover { background-color: $welcome-action-color; color: get-color-accessible-for-background($welcome-action-color) } } &__image { display: none; } } @include desktop { .welcome__image { display: flex; justify-content: center; align-items: center; z-index: -1; position: absolute; top: 50%; right: 0; height: 70%; width: 24%; overflow: hidden; transform: translate(0, -50%); img { display: block; margin: auto; max-width: 200px; max-height: 100%; } } // Override for RTL layout if RTL is enabled .rtl__image { right: auto !important; left: 0; } } ================================================ FILE: themes/conventional-commits/static/css/scss/style.scss ================================================ @import 'base/base'; @import 'layout/header'; @import 'layout/footer'; @import 'layout/welcome'; @import "components/dropdown"; @import "components/banner-image"; @import "themes/markdown"; @import "themes/conventional-commits"; @import "vendors/github-markdown-css"; ================================================ FILE: themes/conventional-commits/static/css/scss/themes/_conventional-commits.scss ================================================ .conventional-commits--loading { .dropdown__options { height: 0 !important; box-shadow: none !important; } } ================================================ FILE: themes/conventional-commits/static/css/scss/themes/_markdown.scss ================================================ @import "./../abstracts/index"; main article.markdown-body { h1{ font-size: 2.3em; } h1, h2, h3, h4, h5, h6, a { font-weight: bold; color: $color-primary-heading; } a.anchorjs-link:hover { text-decoration: none; } } ================================================ FILE: themes/conventional-commits/static/css/scss/vendors/github-markdown-css.scss ================================================ @import "./../../../../node_modules/github-markdown-css/github-markdown"; ================================================ FILE: themes/conventional-commits/static/js/index.js ================================================ import AnchorJS from 'anchor-js'; class App { constructor(anchors) { this.anchors = anchors; this.onInit(); } _addEventListeners() { // using 'load' instead of 'DOMContentLoaded' because we want to wait the css // https://javascript.info/onload-ondomcontentloaded window.addEventListener('load', () => { // wrapped in a timeout for wait css parsing setTimeout(() => this._onPageLoaded(), 0); }); } _onPageLoaded() { this.removeLoadingClass(); } onInit() { this.addAnchorsLinks(); this._addEventListeners(); } addAnchorsLinks() { this.anchors.options = {placement: 'left'}; this.anchors.add(); } removeLoadingClass() { document.body.classList.remove('conventional-commits--loading'); } } const app = new App(new AnchorJS()); ================================================ FILE: themes/conventional-commits/theme.toml ================================================ name = "Conventional Commits" license = "MIT" description = "Hugo theme for Conventional Commits website" homepage = "https://github.com/lorenzodianni/hugo-conventional-commits-theme" tags = [] features = [] min_version = "0.42"