andrius
/
arm-trusted-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge changes from topic "ck/changelog" into integration 

* changes:
  docs(changelog): categorize scopes
  docs(commit-style): add commit style documentation
  build(docs): introduce release script
  build(docs): add support for Markdown documentation
  build(hooks): add commitlint checks for trailers
  build(npm): add Standard Version v9.3.2
  build(npm): add additional package metadata
  build(npm): add license field
  build(npm): update Husky to v7.0.4
  build(npm): update commitlint to v14.1.0
  build(npm): update lockfile format to v2
  docs(prerequisites): update to Node.js v16
  build(docs): update Python dependencies
  build(docs): pin Python dependencies
This commit is contained in:
Manish Pandey 2021-11-18 16:00:01 +01:00 committed by TrustedFirmware Code Review
parent 7300434afc 953910b06a
commit 5d26e27abc
25 changed files with 10308 additions and 4982 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
.commitlintrc.js Normal file
View File

@ -0,0 +1,52 @@
/*
* Copyright (c) 2021, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
/* eslint-env es6 */
"use strict";
const cz = require("./.cz.json");
const { "trailer-exists": trailerExists } = require("@commitlint/rules").default;
/*
* Recursively fetch the project's supported scopes from the Commitizen configuration file. We use
* permit only the blessed scope for each section to encourage developers to use a consistent scope
* scheme.
*/
function getScopes(sections) {
return sections.flatMap(section => {
const scopes = section.scopes;
const subscopes = getScopes(section.sections || []);
const scope = scopes ? [ scopes[0] ] : []; /* Only use the blessed scope */
return scope.concat(subscopes);
})
};
const scopes = getScopes(cz.sections); /* Contains every blessed scope */
module.exports = {
extends: ["@commitlint/config-conventional"],
plugins: [
{
rules: {
"signed-off-by-exists": trailerExists,
"change-id-exists": trailerExists,
},
},
],
rules: {
"body-max-line-length": [1, "always", cz.maxLineWidth], /* Warning */
"header-max-length": [1, "always", cz.maxHeaderWidth], /* Warning */
"change-id-exists": [1, "always", "Change-Id:"], /* Warning */
"signed-off-by-exists": [1, "always", "Signed-off-by:"], /* Warning */
"scope-case": [2, "always", "kebab-case"], /* Error */
"scope-enum": [1, "always", scopes] /* Warning */
},
};

825
.cz.json
View File

@ -1,5 +1,826 @@
{
"path": "./node_modules/cz-conventional-changelog",
"maxHeaderWidth": 50,
"maxLineWidth": 72
}
"maxLineWidth": 72,
"types": [
{
"type": "feat",
"title": "New Features",
"description": "A new feature"
},
{
"type": "fix",
"title": "Resolved Issues",
"description": "A bug fix"
},
{
"type": "build",
"title": "Build System",
"description": "Changes that affect the build system or external dependencies",
"hidden": true
},
{
"type": "ci",
"title": "Continuous Integration",
"description": "Changes to our CI configuration files and scripts",
"hidden": true
},
{
"type": "docs",
"title": "Build System",
"description": "Documentation-only changes",
"hidden": true
},
{
"type": "perf",
"title": "Performance Improvements",
"description": "A code change that improves performance",
"hidden": true
},
{
"type": "refactor",
"title": "Code Refactoring",
"description": "A code change that neither fixes a bug nor adds a feature",
"hidden": true
},
{
"type": "revert",
"title": "Reverted Changes",
"description": "Changes that revert a previous change",
"hidden": true
},
{
"type": "style",
"title": "Style",
"description": "Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)",
"hidden": true
},
{
"type": "test",
"title": "Tests",
"description": "Adding missing tests or correcting existing tests",
"hidden": true
},
{
"type": "chore",
"title": "Miscellaneous",
"description": "Any other change",
"hidden": true
}
],
"sections": [
{
"title": "Architecture",
"sections": [
{
"title": "Activity Monitors Extension (FEAT_AMU)",
"scopes": ["amu"]
},
{
"title": "Support for the `HCRX_EL2` register (FEAT_HCX)",
"scopes": ["hcx"]
},
{
"title": "Memory Partitioning and Monitoring (MPAM) Extension (FEAT_MPAM)",
"scopes": ["mpam"]
},
{
"title": "Scalable Matrix Extension (FEAT_SME)",
"scopes": ["sme"]
},
{
"title": "Scalable Vector Extension (FEAT_SVE)",
"scopes": ["sve"]
},
{
"title": "Trace Buffer Extension (FEAT_TRBE)",
"scopes": ["trbe"]
},
{
"title": "Self-hosted Trace Extensions (FEAT_TRF)",
"scopes": ["trf", "sys_reg_trace"]
}
]
},
{
"title": "Platforms",
"sections": [
{
"title": "Allwinner",
"scopes": ["allwinner", "plat/allwinner"]
},
{
"title": "Arm",
"scopes": ["arm", "plat/arm"],
"sections": [
{
"title": "FPGA",
"scopes": ["fpga", "arm_fgpa", "arm_fpga", "plat/arm_fpga"]
},
{
"title": "FVP",
"scopes": ["fvp", "plat/fvp"]
},
{
"title": "FVP-R",
"scopes": ["fvp-r", "fvp_r"]
},
{
"title": "Juno",
"scopes": ["juno"]
},
{
"title": "Morello",
"scopes": ["morello"]
},
{
"title": "RD",
"scopes": ["rd"],
"sections": [
{
"title": "RD-N2",
"scopes": ["rdn2", "board/rdn2"]
}
]
},
{
"title": "SGI",
"scopes": ["sgi", "plat/sgi", "plat/arm/sgi" ]
},
{
"title": "TC",
"scopes": ["tc"],
"sections": [
{
"title": "TC0",
"scopes": ["tc0", "plat/tc0"]
}
]
}
]
},
{
"title": "Marvell",
"scopes": ["marvell", "plat/marvell"],
"sections": [
{
"title": "Armada",
"scopes": ["armada", "plat/marvell/armada"],
"sections": [
{
"title": "A3K",
"scopes": ["a3k", "plat/marvell/a3k"]
},
{
"title": "A8K",
"scopes": ["a8k", "plat/marvell/a8k"]
}
]
}
]
},
{
"title": "MediaTek",
"scopes": ["mediatek", "plat/mediatek/common", "plat/mediatek"],
"sections": [
{
"title": "MT8183",
"scopes": ["mt8183", "plat/mediatek/mt8183"]
},
{
"title": "MT8192",
"scopes": ["mt8192", "plat/mdeiatek/mt8192"]
},
{
"title": "MT8195",
"scopes": ["mt8195", "plat/mediatek/me8195", "plat/mediatek/mt8195", "plat/mdeiatek/mt8195"]
}
]
},
{
"title": "NVIDIA",
"scopes": ["nvidia"],
"sections": [
{
"title": "Tegra",
"scopes": ["tegra", "plat/tegra"],
"sections": [
{
"title": "Tegra 132",
"scopes": ["tegra132"]
}
]
}
]
},
{
"title": "NXP",
"scopes": ["nxp", "plat/nxp", "plat/nxp/common"],
"sections": [
{
"title": "i.MX",
"scopes": ["imx", "plat/imx", "plat/imx/imx"],
"sections": [
{
"title": "i.MX 8M",
"scopes": ["imx8m", "plat/imx8m", "plat/imx/imx8m"],
"sections": [
{
"title": "i.MX 8M Mini",
"scopes": ["imx8mm", "plat/imx/imx8m/imx8mm"]
},
{
"title": "i.MX 8M Plus",
"scopes": ["imx8mp", "plat/imx/imx8m/imx8mp"]
}
]
}
]
},
{
"title": "Layerscape",
"scopes": ["layerscape", "docs/nxp/layerscape"],
"sections": [
{
"title": "LX2",
"scopes": ["lx2", "plat/nxp/lx2"],
"sections": [
{
"title": "LX216",
"scopes": ["lx216", "plat/nxp/lx216x"],
"sections": [
{
"title": "LX2160",
"scopes": ["lx2160", "plat/soc-lx2160"]
}
]
},
{
"title": "LS1028A",
"scopes": ["ls1028a", "plat/nxp/ls1028a"],
"sections": [
{
"title": "LS1028ARDB",
"scopes": ["ls1028ardb", "plat/nxp/ls1028ardb"]
}
]
}
]
}
]
}
]
},
{
"title": "QEMU",
"scopes": ["qemu", "plat/qemu"]
},
{
"title": "QTI",
"scopes": ["qti"],
"sections": [
{
"title": "SC1780",
"scopes": ["sc7180", "plat/qti/sc7180"]
},
{
"title": "SC7280",
"scopes": ["sc7280", "plat/qti/sc7280"]
}
]
},
{
"title": "Raspberry Pi",
"scopes": ["rpi"],
"sections": [
{
"title": "Raspberry Pi 4",
"scopes": ["rpi4"]
}
]
},
{
"title": "Renesas",
"scopes": ["renesas"],
"sections": [
{
"title": "R-Car",
"scopes": ["rcar", "plat/rcar"],
"sections": [
{
"title": "R-Car 3",
"scopes": ["rcar3", "plat/rcar3"]
}
]
}
]
},
{
"title": "Rockchip",
"scopes": ["rockchip"],
"sections": [
{
"title": "RK3399",
"scopes": ["rk3399", "rockchip/rk3399", "rk3399/suspend"]
}
]
},
{
"title": "Socionext",
"scopes": ["socionext"],
"sections": [
{
"title": "Synquacer",
"scopes": ["synquacer", "plat/synquacer"]
}
]
},
{
"title": "ST",
"scopes": ["st", "plat/st"],
"sections": [
{
"title": "ST32MP1",
"scopes": ["stm32mp1", "plat/st/stm32mp1"]
}
]
},
{
"title": "Xilinx",
"scopes": ["xilinx", "plat/xilinx"],
"sections": [
{
"title": "Versal",
"scopes": ["versal", "plat/xilinx/versal/include", "plat/xilinx/versal", "plat/versal"]
},
{
"title": "ZynqMP",
"scopes": ["zynqmp", "plat/zynqmp", "plat/xilinx/zynqmp"]
}
]
}
]
},
{
"title": "Bootloader Images",
"scopes": ["bl", "bl_common"],
"sections": [
{
"title": "BL1",
"scopes": ["bl1"]
},
{
"title": "BL2",
"scopes": ["bl2"]
}
]
},
{
"title": "Services",
"scopes": ["services"],
"sections": [
{
"title": "FF-A",
"scopes": ["ffa", "ff-a"]
},
{
"title": "RME",
"scopes": ["rme"]
},
{
"title": "SPM",
"scopes": ["spm", "spmc", "spmd", "SPMD", "spm_mm"]
}
]
},
{
"title": "Libraries",
"sections": [
{
"title": "CPU Support",
"scopes": ["cpus", "cpu", "errata", "errata_report"]
},
{
"title": "EL3 Runtime",
"scopes": ["el3-runtime", "el3_runtime"]
},
{
"title": "FCONF",
"scopes": ["fconf"]
},
{
"title": "MPMM",
"scopes": ["mpmm"]
},
{
"title": "OP-TEE",
"scopes": ["optee", "lib/optee"]
},
{
"title": "PSCI",
"scopes": ["psci"]
},
{
"title": "GPT",
"scopes": ["gpt", "gpt_rme"]
},
{
"title": "SMCCC",
"scopes": ["smccc"]
},
{
"title": "Translation Tables",
"scopes": ["xlat"]
}
]
},
{
"title": "Drivers",
"sections": [
{
"title": "Authentication",
"scopes": ["auth", "driver/auth"],
"sections": [
{
"title": "CryptoCell-713",
"scopes": ["cc-713"]
}
]
},
{
"title": "FWU",
"scopes": ["fwu", "fwu_metadata"]
},
{
"title": "I/O",
"scopes": ["io"],
"sections": [
{
"title": "MTD",
"scopes": ["mtd", "io_mtd"]
}
]
},
{
"title": "Measured Boot",
"scopes": ["measured-boot", "measured boot", "measured_boot"]
},
{
"title": "MMC",
"scopes": ["mmc", "drivers/mmc"]
},
{
"title": "MTD",
"scopes": ["mtd", "drivers/mtd"],
"sections": [
{
"title": "NAND",
"scopes": ["nand"],
"sections": [
{
"title": "SPI NAND",
"scopes": ["spi-nand", "spi_nand"]
}
]
}
]
},
{
"title": "SCMI",
"scopes": ["scmi", "scmi_common", "drivers/scmi-msg"]
},
{
"title": "UFS",
"scopes": ["ufs"]
},
{
"title": "Arm",
"scopes": ["arm-drivers"],
"sections": [
{
"title": "Ethos-N",
"scopes": ["ethos-n", "drivers/arm/ethosn"]
},
{
"title": "GIC",
"scopes": ["gic"],
"sections": [
{
"title": "GICv3",
"scopes": ["gicv3"],
"sections": [
{
"title": "GIC-600AE",
"scopes": ["gic600ae"]
}
]
}
]
},
{
"title": "TZC",
"scopes": ["tzc"],
"sections": [
{
"title": "TZC-400",
"scopes": ["tzc400", "drivers/tzc400"]
}
]
}
]
},
{
"title": "Marvell",
"scopes": ["marvell-drivers"],
"sections": [
{
"title": "COMPHY",
"scopes": ["marvell-comphy", "drivers/marvell/comphy"],
"sections": [
{
"title": "Armada 3700",
"scopes": ["marvell-comphy-3700", "drivers/marvell/comphy-3700"]
},
{
"title": "CP110",
"scopes": ["marvell-comphy-cp110", "drivers/marvell/comphy-cp110"]
}
]
},
{
"title": "UART",
"scopes": ["marvell-uart", "plat/marvell/uart"]
},
{
"title": "Armada",
"scopes": ["armada-drivers"],
"sections": [
{
"title": "A3K",
"scopes": ["a3k-drivers"],
"sections": [
{
"title": "A3720",
"scopes": ["a3720-uart", "plat/marvell/a3720/uart"]
}
]
}
]
}
]
},
{
"title": "MediaTek",
"scopes": ["mediatek-drivers"],
"sections": [
{
"title": "APU",
"scopes": ["mediatek-apu", "plat/mediatek/apu"]
},
{
"title": "EMI MPU",
"scopes": ["mediatek-emi-mpu", "plat/mediatek/mpu"]
},
{
"title": "PMIC Wrapper",
"scopes": ["mediatek-pmic-wrapper", "plat/mediatek/pmic_wrap"]
},
{
"title": "MT8192",
"scopes": ["mt8192-drivers"],
"sections": [
{
"title": "SPM",
"scopes": ["mt8192-spm", "mediatek/mt8192/spm"]
}
]
}
]
},
{
"title": "NXP",
"scopes": ["nxp-drivers"],
"sections": [
{
"title": "DCFG",
"scopes": ["nxp-dcfg", "driver/nxp/dcfg"]
},
{
"title": "FLEXSPI",
"scopes": ["flexspi", "include/drivers/flexspi", "driver/nxp/xspi"]
},
{
"title": "SCFG",
"scopes": ["nxp-scfg", "nxp/scfg"]
},
{
"title": "SFP",
"scopes": ["nxp-sfp", "drivers/nxp/sfp"]
}
]
},
{
"title": "Renesas",
"scopes": ["renesas-drivers"],
"sections": [
{
"title": "R-Car3",
"scopes": ["rcar3-drivers", "drivers/rcar3"]
}
]
},
{
"title": "ST",
"scopes": ["st-drivers", "drivers/st"],
"sections": [
{
"title": "Clock",
"scopes": ["st-clock", "stm32mp_clk", "drivers/st/clk", "stm32mp1_clk"]
},
{
"title": "I/O",
"scopes": ["st-io-drivers"],
"sections": [
{
"title": "STM32 Image",
"scopes": ["st-io-stm32image", "io-stm32image", "io_stm32image"]
}
]
},
{
"title": "SDMMC2",
"scopes": ["st-sdmmc2", "stm32_sdmmc2"]
},
{
"title": "ST PMIC",
"scopes": ["st-pmic", "drivers/st/pmic"]
},
{
"title": "STPMIC1",
"scopes": ["stpmic1"]
},
{
"title": "UART",
"scopes": ["st-uart"],
"sections": [
{
"title": "STM32 Console",
"scopes": ["stm32-console", "stm32_console"]
}
]
},
{
"title": "USB",
"scopes": ["st-usb", "drivers/st/usb"]
}
]
},
{
"title": "USB",
"scopes": ["usb", "drivers/usb"]
}
]
},
{
"title": "Miscellaneous",
"sections": [
{
"title": "AArch64",
"scopes": ["aarch64"]
},
{
"title": "Debug",
"scopes": ["debug", "common/debug"]
},
{
"title": "CRC32",
"scopes": ["crc32"],
"sections": [
{
"title": "Hardware CRC32",
"scopes": ["hw-crc32", "hw_crc", "hw_crc32"]
},
{
"title": "Software CRC32",
"scopes": ["sw-crc32", "sw_crc32"]
}
]
},
{
"title": "DT Bindings",
"scopes": ["dt-bindings"]
},
{
"title": "FDT Wrappers",
"scopes": ["fdt-wrappers"]
},
{
"title": "FDTs",
"scopes": ["fdts", "fdt"],
"sections": [
{
"title": "Morello",
"scopes": ["morello-fdts", "fdts/morello"]
},
{
"title": "STM32MP1",
"scopes": ["stm32mp1-fdts", "fdts stm32mp1"]
}
]
},
{
"title": "PIE",
"scopes": ["pie"]
},
{
"title": "Security",
"scopes": ["security"]
},
{
"title": "SDEI",
"scopes": ["sdei"]
},
{
"title": "TBBR",
"scopes": ["tbbr"]
},
{
"title": "NXP",
"sections": [
{
"title": "OCRAM",
"scopes": ["nxp-ocram", "nxp/common/ocram"]
},
{
"title": "PSCI",
"scopes": ["nxp-psci", "plat/nxp/common/psci"]
}
]
}
]
},
{
"title": "Documentation",
"scopes": ["docs", "doc"],
"sections": [
{
"title": "Changelog",
"scopes": ["changelog"]
},
{
"title": "Commit Style",
"scopes": ["commit-style"]
},
{
"title": "Contribution Guidelines",
"scopes": ["contributing", "contribution-guidelines", "docs-contributing.rst"]
},
{
"title": "Maintainers",
"scopes": ["maintainers"]
},
{
"title": "Prerequisites",
"scopes": ["prerequisites"]
}
]
},
{
"title": "Build System",
"scopes": ["build", "makefile", "Makefile"],
"sections": [
{
"title": "Git Hooks",
"scopes": ["hooks"]
}
]
},
{
"title": "Tools",
"sections": [
{
"title": "STM32 Image",
"scopes": ["stm32image", "tools/stm32image"]
}
]
},
{
"title": "Dependencies",
"scopes": ["deps"],
"sections": [
{
"title": "checkpatch",
"scopes": ["checkpatch"]
},
{
"title": "libfdt",
"scopes": ["libfdt"]
},
{
"title": "Node Package Manager (NPM)",
"scopes": ["npm"]
}
]
}
]
}

66
.versionrc.js Normal file
View File

@ -0,0 +1,66 @@
/*
* Copyright (c) 2021, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
/* eslint-env es6 */
"use strict";
const cz = require("./.cz.json");
/*
* Convert the Commitizen types array into the format accepted by the Conventional Changelog
* Conventional Commits plugin (which our own plugin extends).
*/
const types = cz.types.map(type => {
if (!type.hidden) {
/*
* Conventional Changelog prevents each section from appearing only if it has no designated
* title, regardless of the value of the `hidden` flag.
*/
type.section = type.title;
}
delete type.title;
delete type.description;
return type;
});
module.exports = {
"header": "# Change Log & Release Notes\n\nThis document contains a summary of the new features, changes, fixes and known\nissues in each release of Trusted Firmware-A.\n",
"preset": {
"name": "tf-a",
"commitUrlFormat": "https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/{{hash}}",
"compareUrlFormat": "https://review.trustedfirmware.org/plugins/gitiles/TF-A/trusted-firmware-a/+/{{previousTag}}..{{currentTag}}",
"userUrlFormat": "https://github.com/{{user}}",
"types": types,
"sections": cz.sections,
},
"bumpFiles": [
{
"filename": "Makefile",
"updater": {
"readVersion": function (contents) {
const major = contents.match(/^VERSION_MAJOR\s*:=\s*(\d+?)$/m)[1];
const minor = contents.match(/^VERSION_MINOR\s*:=\s*(\d+?)$/m)[1];
return `${major}.${minor}.0`;
},
"writeVersion": function (contents, version) {
const major = version.split(".")[0];
const minor = version.split(".")[1];
contents = contents.replace(/^(VERSION_MAJOR\s*:=\s*)(\d+?)$/m, `$1${major}`);
contents = contents.replace(/^(VERSION_MINOR\s*:=\s*)(\d+?)$/m, `$1${minor}`);
return contents;
}
}
}
]
};

14
commitlint.config.js
View File

@ -1,14 +0,0 @@
/* eslint-env node */
"use strict";
const config = require("./.cz.json");
module.exports = {
extends: ["@commitlint/config-conventional"],
rules: {
"header-max-length": [1, "always", config.maxHeaderWidth], /* Warning */
"body-max-line-length": [1, "always", config.maxLineWidth], /* Warning */
"signed-off-by": [0, "always", "Signed-off-by:"] /* Disabled - buggy */
}
};

6
docs/about/maintainers.rst
View File

@ -747,6 +747,12 @@ Threat Model
:|G|: `vwadekar`_
:|F|: docs/threat_model/
Conventional Changelog Extensions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:|M|: Chris Kay <chris.kay@arm.com>
:|G|: `CJKay`_
:|F|: tools/conventional-changelog-tf-a
.. _AlexeiFedorov: https://github.com/AlexeiFedorov
.. _Andre-ARM: https://github.com/Andre-ARM
.. _Anson-Huang: https://github.com/Anson-Huang

3766
docs/change-log.md Normal file
View File

File diff suppressed because it is too large Load Diff

4602
docs/change-log.rst
View File

File diff suppressed because it is too large Load Diff

4
docs/conf.py
View File

@ -20,13 +20,13 @@ project = 'Trusted Firmware-A'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.plantuml']
extensions = ['myst_parser', 'sphinx.ext.autosectionlabel', 'sphinxcontrib.plantuml']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
source_suffix = '.rst'
source_suffix = ['.md', '.rst']
# The master toctree document.
master_doc = 'index'

8
docs/getting_started/prerequisites.rst
View File

@ -75,7 +75,7 @@ These tools are optional:
The standard software package used for debugging software on Arm development
platforms and |FVP| models.
- Node.js >= 14
- Node.js >= 16
Highly recommended, and necessary in order to install and use the packaged
Git hooks and helper tools. Without these tools you will need to rely on the
@ -98,13 +98,13 @@ The optional packages can be installed using:
sudo apt install device-tree-compiler
Additionally, to install an up-to-date version of Node.js, you can use the `Node
Version Manager`_ to install a version of your choosing (we recommend 14, but
Version Manager`_ to install a version of your choosing (we recommend 16, but
later LTS versions might offer a more stable experience):
.. code:: shell
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | "$SHELL"
exec "$SHELL" -ic "nvm install 14; exec $SHELL"
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | "$SHELL"
exec "$SHELL" -ic "nvm install 16; exec $SHELL"
.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script

163
docs/process/commit-style.rst Normal file
View File

@ -0,0 +1,163 @@
Commit Style
============
When writing commit messages, please think carefully about the purpose and scope
of the change you are making: describe briefly what the change does, and
describe in detail why it does it. This helps to ensure that changes to the
code-base are transparent and approachable to reviewers, and it allows us to
keep a more accurate changelog. You may use Markdown in commit messages.
A good commit message provides all the background information needed for
reviewers to understand the intent and rationale of the patch. This information
is also useful for future reference.
For example:
- What does the patch do?
- What motivated it?
- What impact does it have?
- How was it tested?
- Have alternatives been considered? Why did you choose this approach over
another one?
- If it fixes an `issue`_, include a reference.
|TF-A| follows the `Conventional Commits`_ specification. All commits to the
main repository are expected to adhere to these guidelines, so it is
**strongly** recommended that you read at least the `quick summary`_ of the
specification.
To briefly summarize, commit messages are expected to be of the form:
.. code::
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The following example commit message demonstrates the use of the
``refactor`` type and the ``amu`` scope:
.. code::
refactor(amu): factor out register accesses
This change introduces a small set of register getters and setters to
avoid having to repeatedly mask and shift in complex code.
Change-Id: Ia372f60c5efb924cd6eeceb75112e635ad13d942
Signed-off-by: Chris Kay <chris.kay@arm.com>
The following `types` are permissible and are strictly enforced:
+--------------+---------------------------------------------------------------+
| Scope | Description |
+==============+===============================================================+
| ``feat`` | A new feature |
+--------------+---------------------------------------------------------------+
| ``fix`` | A bug fix |
+--------------+---------------------------------------------------------------+
| ``build`` | Changes that affect the build system or external dependencies |
+--------------+---------------------------------------------------------------+
| ``ci`` | Changes to our CI configuration files and scripts |
+--------------+---------------------------------------------------------------+
| ``docs`` | Documentation-only changes |
+--------------+---------------------------------------------------------------+
| ``perf`` | A code change that improves performance |
+--------------+---------------------------------------------------------------+
| ``refactor`` | A code change that neither fixes a bug nor adds a feature |
+--------------+---------------------------------------------------------------+
| ``revert`` | Changes that revert a previous change |
+--------------+---------------------------------------------------------------+
| ``style`` | Changes that do not affect the meaning of the code |
| | (white-space, formatting, missing semi-colons, etc.) |
+--------------+---------------------------------------------------------------+
| ``test`` | Adding missing tests or correcting existing tests |
+--------------+---------------------------------------------------------------+
| ``chore`` | Any other change |
+--------------+---------------------------------------------------------------+
The permissible `scopes` are more flexible, and we maintain a list of them in
our :download:`Commitizen configuration file <../../.cz.json>`. Scopes in this
file are organized by their changelog section, each of which may have one or
more accepted scopes, but only the first of which is considered to be "blessed".
Scopes that are not blessed exist for changes submitted before scope enforcement
came into effect, and are considered deprecated.
While we don't enforce scopes strictly, we do ask that commits use these if they
can, or add their own if no appropriate one exists (see :ref:`Adding Scopes`).
It's highly recommended that you use the tooling installed by the optional steps
in the :ref:`prerequisites <Prerequisites>` guide to validate commit messages
locally, as commitlint reports a live list of the acceptable scopes.
.. _Adding Scopes:
Adding Scopes
-------------
Scopes that are either a) unblessed in the configuration file, or b) do not
exist in the configuration file at all are considered to be deprecated. If you
are adding a new component that does not yet have a designated scope, please
feel free to add one.
For example, if you are adding or making modifications to `Foo`'s latest and
greatest new platform `Bar`, you would add it to the `Platforms` changelog
section, and the hierarchy should look something like this:
.. code:: json
{
"sections": [
{
"title": "Platforms",
"sections": [
{
"title": "Foo",
"scopes": ["foo"],
"sections": [
{
"title": "Bar",
"scopes": ["bar"]
}
]
}
]
}
]
}
When creating new scopes, try to keep them short and succinct, and use kebab
case (``this-is-kebab-case``). Components with a product name (i.e. most
platforms and some drivers) should use that name (e.g. ``gic600ae``,
``flexspi``, ``stpmic1``), otherwise use a name that uniquely represents the
component (e.g. ``marvell-comphy-3700``, ``rcar3-drivers``, ``a3720-uart``).
Mandated Trailers
-----------------
Commits are expected to be signed off with the ``Signed-off-by:`` trailer using
your real name and email address. You can do this automatically by committing
with Git's ``-s`` flag.
There may be multiple ``Signed-off-by:`` lines depending on the history of the
patch, but one **must** be the committer. More details may be found in the
`Gerrit Signed-off-by Lines guidelines`_.
Ensure that each commit also has a unique ``Change-Id:`` line. If you have
followed optional steps in the prerequisites to either install the Node.js tools
or clone the repository using the "`Clone with commit-msg hook`" clone method,
then this should be done automatically for you.
More details may be found in the `Gerrit Change-Ids documentation`_.
--------------
*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0
.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
.. _issue: https://developer.trustedfirmware.org/project/board/1/
.. _quick summary: https://www.conventionalcommits.org/en/v1.0.0/#summary

53
docs/process/contributing.rst
View File

@ -26,23 +26,11 @@ Getting Started
Making Changes
--------------
- Ensure commits adhere to the the project's :ref:`Commit Style`.
- Make commits of logical units. See these general `Git guidelines`_ for
contributing to a project.
- Ensure your commit messages comply with the `Conventional Commits`_
specification:
.. code::
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
You can use the tooling installed by the optional steps in the
:ref:`prerequisites <Prerequisites>` guide to validate this locally.
- Keep the commits on topic. If you need to fix another bug or make another
enhancement, please address it on a separate topic branch.
@ -52,39 +40,6 @@ Making Changes
- Avoid long commit series. If you do have a long series, consider whether
some commits should be squashed together or addressed in a separate topic.
- Ensure that each commit in the series has at least one ``Signed-off-by:``
line, using your real name and email address. The names in the
``Signed-off-by:`` and ``Commit:`` lines must match. By adding this line the
contributor certifies the contribution is made under the terms of the
:download:`Developer Certificate of Origin <../../dco.txt>`.
There might be multiple ``Signed-off-by:`` lines, depending on the history
of the patch.
More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
- Ensure that each commit also has a unique ``Change-Id:`` line. If you have
cloned the repository with the "`Clone with commit-msg hook`" clone method
(following the :ref:`Prerequisites` document), this should already be the
case.
More details may be found in the `Gerrit Change-Ids documentation`_.
- Write informative and comprehensive commit messages. A good commit message
provides all the background information needed for reviewers to understand
the intent and rationale of the patch. This information is also useful for
future reference.
For example:
- What does the patch do?
- What motivated it?
- What impact does it have?
- How was it tested?
- Have alternatives been considered? Why did you choose this approach over
another one?
- If it fixes an `issue`_, include a reference.
- Follow the :ref:`Coding Style` and :ref:`Coding Guidelines`.
- Use the checkpatch.pl script provided with the Linux source tree. A
@ -289,15 +244,11 @@ Binary Components
*Copyright (c) 2013-2021, Arm Limited and Contributors. All rights reserved.*
.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0
.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
.. _review.trustedfirmware.org: https://review.trustedfirmware.org
.. _issue: https://developer.trustedfirmware.org/project/board/1/
.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
.. _Git guidelines: http://git-scm.com/book/ch5-2.html
.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io
.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries
.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst

1
docs/process/index.rst
View File

@ -8,6 +8,7 @@ Processes & Policies
security
platform-compatibility-policy
commit-style
coding-style
coding-guidelines
contributing

5
docs/requirements.in Normal file
View File

@ -0,0 +1,5 @@
myst-parser==0.15.2
pip-tools==6.4.0
sphinx==4.2.0
sphinx-rtd-theme==1.0.0
sphinxcontrib-plantuml==0.22

94
docs/requirements.txt
View File

@ -1,3 +1,91 @@
sphinx>=2.0.0
sphinx-rtd-theme>=0.4.3
sphinxcontrib-plantuml>=0.15
#
# This file is autogenerated by pip-compile with python 3.8
# To update, run:
#
# pip-compile
#
alabaster==0.7.12
# via sphinx
attrs==21.2.0
# via markdown-it-py
babel==2.9.1
# via sphinx
certifi==2021.5.30
# via requests
charset-normalizer==2.0.4
# via requests
click==8.0.1
# via pip-tools
docutils==0.16
# via
# myst-parser
# sphinx
# sphinx-rtd-theme
idna==3.2
# via requests
imagesize==1.2.0
# via sphinx
jinja2==3.0.1
# via
# myst-parser
# sphinx
markdown-it-py==1.1.0
# via
# mdit-py-plugins
# myst-parser
markupsafe==2.0.1
# via jinja2
mdit-py-plugins==0.2.8
# via myst-parser
myst-parser==0.15.2
# via -r requirements.in
packaging==21.0
# via sphinx
pep517==0.11.0
# via pip-tools
pip-tools==6.4.0
# via -r requirements.in
pygments==2.10.0
# via sphinx
pyparsing==2.4.7
# via packaging
pytz==2021.1
# via babel
pyyaml==6.0
# via myst-parser
requests==2.26.0
# via sphinx
snowballstemmer==2.1.0
# via sphinx
sphinx==4.2.0
# via
# -r requirements.in
# myst-parser
# sphinx-rtd-theme
# sphinxcontrib-plantuml
sphinx-rtd-theme==1.0.0
# via -r requirements.in
sphinxcontrib-applehelp==1.0.2
# via sphinx
sphinxcontrib-devhelp==1.0.2
# via sphinx
sphinxcontrib-htmlhelp==2.0.0
# via sphinx
sphinxcontrib-jsmath==1.0.1
# via sphinx
sphinxcontrib-plantuml==0.22
# via -r requirements.in
sphinxcontrib-qthelp==1.0.3
# via sphinx
sphinxcontrib-serializinghtml==1.1.5
# via sphinx
tomli==1.2.1
# via pep517
urllib3==1.26.6
# via requests
wheel==0.37.0
# via pip-tools
# The following packages are considered to be unsafe in a requirements file:
# pip
# setuptools

5313
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

14
package.json
View File

@ -1,13 +1,19 @@
{
"name": "trusted-firmware-a",
"version": "2.5.0",
"license": "BSD-3-Clause",
"private": true,
"scripts": {
"postinstall": "husky install"
"postinstall": "husky install",
"release": "standard-version -i docs/change-log.md"
},
"devDependencies": {
"@commitlint/cli": "^11.0.0",
"@commitlint/config-conventional": "^11.0.0",
"@commitlint/cli": "^14.1.0",
"@commitlint/config-conventional": "^14.1.0",
"commitizen": "^4.2.4",
"conventional-changelog-tf-a": "file:tools/conventional-changelog-tf-a",
"cz-conventional-changelog": "^3.3.0",
"husky": "^5.0.4"
"husky": "^7.0.4",
"standard-version": "^9.3.2"
}
}

222
tools/conventional-changelog-tf-a/index.js Normal file
View File

@ -0,0 +1,222 @@
/*
* Copyright (c) 2021, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
/* eslint-env es6 */
"use strict";
const Handlebars = require("handlebars");
const Q = require("q");
const _ = require("lodash");
const ccConventionalChangelog = require("conventional-changelog-conventionalcommits/conventional-changelog");
const ccParserOpts = require("conventional-changelog-conventionalcommits/parser-opts");
const ccRecommendedBumpOpts = require("conventional-changelog-conventionalcommits/conventional-recommended-bump");
const ccWriterOpts = require("conventional-changelog-conventionalcommits/writer-opts");
const execa = require("execa");
const readFileSync = require("fs").readFileSync;
const resolve = require("path").resolve;
/*
* Register a Handlebars helper that lets us generate Markdown lists that can support multi-line
* strings. This is driven by inconsistent formatting of breaking changes, which may be multiple
* lines long and can terminate the list early unintentionally.
*/
Handlebars.registerHelper("tf-a-mdlist", function (indent, options) {
const spaces = new Array(indent + 1).join(" ");
const first = spaces + "- ";
const nth = spaces + " ";
return first + options.fn(this).replace(/\n(?!\s*\n)/gm, `\n${nth}`).trim() + "\n";
});
/*
* Register a Handlebars helper that concatenates multiple variables. We use this to generate the
* title for the section partials.
*/
Handlebars.registerHelper("tf-a-concat", function () {
let argv = Array.prototype.slice.call(arguments, 0);
argv.pop();
return argv.join("");
});
function writerOpts(config) {
/*
* Flatten the configuration's sections list. This helps us iterate over all of the sections
* when we don't care about the hierarchy.
*/
const flattenSections = function (sections) {
return sections.flatMap(section => {
const subsections = flattenSections(section.sections || []);
return [section].concat(subsections);
})
};
const flattenedSections = flattenSections(config.sections);
/*
* Register a helper to return a restructured version of the note groups that includes notes
* categorized by their section.
*/
Handlebars.registerHelper("tf-a-notes", function (noteGroups, options) {
const generateTemplateData = function (sections, notes) {
return (sections || []).flatMap(section => {
const templateData = {
title: section.title,
sections: generateTemplateData(section.sections, notes),
notes: notes.filter(note => section.scopes?.includes(note.commit.scope)),
};
/*
* Don't return a section if it contains no notes and no sub-sections.
*/
if ((templateData.sections.length == 0) && (templateData.notes.length == 0)) {
return [];
}
return [templateData];
});
};
return noteGroups.map(noteGroup => {
return {
title: noteGroup.title,
sections: generateTemplateData(config.sections, noteGroup.notes),
notes: noteGroup.notes.filter(note =>
!flattenedSections.some(section => section.scopes?.includes(note.commit.scope))),
};
});
});
/*
* Register a helper to return a restructured version of the commit groups that includes commits
* categorized by their section.
*/
Handlebars.registerHelper("tf-a-commits", function (commitGroups, options) {
const generateTemplateData = function (sections, commits) {
return (sections || []).flatMap(section => {
const templateData = {
title: section.title,
sections: generateTemplateData(section.sections, commits),
commits: commits.filter(commit => section.scopes?.includes(commit.scope)),
};
/*
* Don't return a section if it contains no notes and no sub-sections.
*/
if ((templateData.sections.length == 0) && (templateData.commits.length == 0)) {
return [];
}
return [templateData];
});
};
return commitGroups.map(commitGroup => {
return {
title: commitGroup.title,
sections: generateTemplateData(config.sections, commitGroup.commits),
commits: commitGroup.commits.filter(commit =>
!flattenedSections.some(section => section.scopes?.includes(commit.scope))),
};
});
});
const writerOpts = ccWriterOpts(config)
.then(writerOpts => {
const ccWriterOptsTransform = writerOpts.transform;
/*
* These configuration properties can't be injected directly into the template because
* they themselves are templates. Instead, we register them as partials, which allows
* them to be evaluated as part of the templates they're used in.
*/
Handlebars.registerPartial("commitUrl", config.commitUrlFormat);
Handlebars.registerPartial("compareUrl", config.compareUrlFormat);
Handlebars.registerPartial("issueUrl", config.issueUrlFormat);
/*
* Register the partials that allow us to recursively create changelog sections.
*/
const notePartial = readFileSync(resolve(__dirname, "./templates/note.hbs"), "utf-8");
const noteSectionPartial = readFileSync(resolve(__dirname, "./templates/note-section.hbs"), "utf-8");
const commitSectionPartial = readFileSync(resolve(__dirname, "./templates/commit-section.hbs"), "utf-8");
Handlebars.registerPartial("tf-a-note", notePartial);
Handlebars.registerPartial("tf-a-note-section", noteSectionPartial);
Handlebars.registerPartial("tf-a-commit-section", commitSectionPartial);
/*
* Override the base templates so that we can generate a changelog that looks at least
* similar to the pre-Conventional Commits TF-A changelog.
*/
writerOpts.mainTemplate = readFileSync(resolve(__dirname, "./templates/template.hbs"), "utf-8");
writerOpts.headerPartial = readFileSync(resolve(__dirname, "./templates/header.hbs"), "utf-8");
writerOpts.commitPartial = readFileSync(resolve(__dirname, "./templates/commit.hbs"), "utf-8");
writerOpts.footerPartial = readFileSync(resolve(__dirname, "./templates/footer.hbs"), "utf-8");
writerOpts.transform = function (commit, context) {
/*
* Fix up commit trailers, which for some reason are not correctly recognized and
* end up showing up in the breaking changes.
*/
commit.notes.forEach(note => {
const trailers = execa.sync("git", ["interpret-trailers", "--parse"], {
input: note.text
}).stdout;
note.text = note.text.replace(trailers, "").trim();
});
return ccWriterOptsTransform(commit, context);
};
return writerOpts;
});
return writerOpts;
}
module.exports = function (parameter) {
const config = parameter || {};
return Q.all([
ccConventionalChangelog(config),
ccParserOpts(config),
ccRecommendedBumpOpts(config),
writerOpts(config)
]).spread((
conventionalChangelog,
parserOpts,
recommendedBumpOpts,
writerOpts
) => {
if (_.isFunction(parameter)) {
return parameter(null, {
gitRawCommitsOpts: { noMerges: null },
conventionalChangelog,
parserOpts,
recommendedBumpOpts,
writerOpts
});
} else {
return {
conventionalChangelog,
parserOpts,
recommendedBumpOpts,
writerOpts
};
}
});
};

12
tools/conventional-changelog-tf-a/package.json Normal file
View File

@ -0,0 +1,12 @@
{
"name": "conventional-changelog-tf-a",
"version": "1.0.0",
"private": true,
"main": "index.js",
"dependencies": {
"conventional-changelog-conventionalcommits": "^4.6.1",
"execa": "^5.1.1",
"lodash": "^4.17.21",
"q": "^1.5.1"
}
}

17
tools/conventional-changelog-tf-a/templates/commit-section.hbs Normal file
View File

@ -0,0 +1,17 @@
{{#if title ~}}
{{ header }}
{{#if commits.length ~}}
{{#each commits ~}}
{{#tf-a-mdlist 0}}{{> commit root=@root showScope=../topLevel }}{{/tf-a-mdlist ~}}
{{/each}}
{{/if ~}}
{{#if sections.length ~}}
{{#each sections ~}}
{{#tf-a-mdlist 0}}{{> tf-a-commit-section root=@root header=(tf-a-concat "**" title "**") }}{{/tf-a-mdlist}}
{{/each}}
{{/if ~}}
{{/if}}

15
tools/conventional-changelog-tf-a/templates/commit.hbs Normal file
View File

@ -0,0 +1,15 @@
{{#if scope }}
{{~#if showScope }}**{{ scope }}:** {{/if}}
{{~/if}}
{{~#if subject }}
{{~ subject }}
{{~else}}
{{~ header }}
{{~/if}}
{{~#if hash }} {{#if @root.linkReferences ~}}
([{{ shortHash }}]({{> commitUrl root=@root }}))
{{~else}}
{{~ shortHash }}
{{~/if}}{{~/if}}

0
tools/conventional-changelog-tf-a/templates/footer.hbs Normal file
View File

13
tools/conventional-changelog-tf-a/templates/header.hbs Normal file
View File

@ -0,0 +1,13 @@
{{#if isPatch~}}
###
{{~else~}}
##
{{~/if}} {{#if @root.linkCompare~}}
[{{version}}]({{> compareUrl root=@root}})
{{~else}}
{{~version}}
{{~/if}}
{{~#if title}} "{{title}}"
{{~/if}}
{{~#if date}} ({{date}})
{{/if}}

13
tools/conventional-changelog-tf-a/templates/note-section.hbs Normal file
View File

@ -0,0 +1,13 @@
{{ header }}
{{#if notes.length ~}}
{{#each notes ~}}
{{#tf-a-mdlist 0}}{{> tf-a-note root=@root showScope=../topLevel }}{{/tf-a-mdlist}}
{{/each ~}}
{{/if ~}}
{{#if sections.length ~}}
{{#each sections ~}}
{{#tf-a-mdlist 0}}{{> tf-a-note-section root=@root header=(tf-a-concat "**" title "**") }}{{/tf-a-mdlist}}
{{/each~}}
{{/if}}

3
tools/conventional-changelog-tf-a/templates/note.hbs Normal file
View File

@ -0,0 +1,3 @@
{{ text }}
**See:** {{#with commit }}{{> commit root=@root showScope=../showScope }}{{/with}}

9
tools/conventional-changelog-tf-a/templates/template.hbs Normal file
View File

@ -0,0 +1,9 @@
{{> header }}
{{#each (tf-a-notes noteGroups) ~}}
{{> tf-a-note-section root=@root header=(tf-a-concat "### ⚠ " title) topLevel=true }}
{{/each ~}}
{{#each (tf-a-commits commitGroups) ~}}
{{> tf-a-commit-section root=@root header=(tf-a-concat "### " title) topLevel=true }}
{{/each ~}}