diff --git a/website/docs/getting-started/glossary/index.mdx b/website/docs/getting-started/glossary/index.mdx index 692dd1d..bd9e6a6 100644 --- a/website/docs/getting-started/glossary/index.mdx +++ b/website/docs/getting-started/glossary/index.mdx @@ -19,9 +19,12 @@ The definitions used in the **xpm** project are listed below. ### xpm -**xpm** is the xPack Project manager. It uses several concepts and definitions: +**xpm** is the **xPack Project Manager**. It uses several concepts and definitions: - **xPacks (xpm packages)**: software packages managed by **xpm**; an extension of **npm** packages +- **author**: from **npm** point of view, the package author is the person who +maintains the package metadata; it may or may not be the same person who wrote the library source code or the binaries +- **contributors**: from **npm** point of view, these are the persons who contributed code to the package, i.e. who wrote the the library source code or the binaries; for 3rd party packages, they are usually different from the package _authors_ - **dependencies**: source packages required by the current project during compile/link time - **development dependencies**: tools required during development of the current project - **actions**: sequences of shell commands executed in the environment of the current project dependencies diff --git a/website/docs/guide/index.mdx b/website/docs/guide/index.mdx index 1a2e85c..813a70c 100644 --- a/website/docs/guide/index.mdx +++ b/website/docs/guide/index.mdx @@ -15,9 +15,10 @@ date: 2024-11-26 01:34:00 +0200 This section is intended for those who plan to add xPack metadata to their projects and provides documentation on how to create new packages. -## Chapters +## Sections 1. [Concepts](./concepts/) 1. [Metadata](../metadata/) - - +1. [Files](../files/) +1. [Project Templates](../project-templates/) +1. [New GitHub Project](../new-github-project/) diff --git a/website/docs/guide/new-github-project/_create-github-project.mdx b/website/docs/guide/new-github-project/_create-github-project.mdx index 2c3f854..fa26d82 100644 --- a/website/docs/guide/new-github-project/_create-github-project.mdx +++ b/website/docs/guide/new-github-project/_create-github-project.mdx @@ -54,17 +54,17 @@ git clone https://github.com//.git .git ### Edit the master `README.md` file -As mentioned in the introduction, -although for original xPacks there are no constraints on how to -organise the branches, for consistency with xPacks that use 3rd -party content, it is recommended to use an `xpack` branch. +As mentioned in the introduction, although there are no constraints +on how to organise branches for original xPacks, it is recommended +to use an `xpack` branch for consistency with xPacks that utilise +third-party content. -In this case, to warn users about this configuration, edit -the `README.md` file; keep the header line and replace the content with: +In this case, to inform users about this configuration, edit the +`README.md` file. Retain the header line and replace the content with: ```text This project does not use the `master` branch, please -switch to the `xpack` branch to get the project files. +switch to the `xpack` branch to access the project files. ``` With VS Code, Fork or Git: @@ -75,10 +75,10 @@ With VS Code, Fork or Git: ### Edit the `LICENSE` file The automatically generated `LICENSE` file already includes the -user name as the copyright owner. When the project is owned by -an organisation, the name refers to the organisation. Probably -this is not exactly what you need, and you might prefer to have -your name in the copyright notice. +username as the copyright owner. When the project is owned by an +organisation, the name refers to the organisation. This may not +be exactly what you need, and you might prefer to have your name +in the copyright notice. Check and possibly adjust to match your `LICENSE` requirements. @@ -87,7 +87,7 @@ For example, xPack projects use: ```text MIT License -Copyright (c) 2022 Liviu Ionescu. All rights reserved. +Copyright (c) 2024 Liviu Ionescu. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy ... @@ -102,6 +102,11 @@ With VS Code, Fork or Git: With VS Code, Fork or Git: -- select the `master` branch -- create new branch `xpack` -- switch to it +
    +
  • select the `master` branch
    • +
  • create a new `xpack` branch
    • +
  • switch to it
    • +{props.doReconstruct === "true" ? (
  • rename LICENSE to LICENSE-XPACK.
    • ) : (<>)} +{props.doReconstruct === "true" ? (
  • rename README.md to README-XPACK.md.
    • ) : (<>)} +
  • Push the `xpack` branch
    • +
diff --git a/website/docs/guide/new-github-project/index.mdx b/website/docs/guide/new-github-project/index.mdx index ebef6e6..8b35bfc 100644 --- a/website/docs/guide/new-github-project/index.mdx +++ b/website/docs/guide/new-github-project/index.mdx @@ -28,105 +28,102 @@ Work in progress. ## Overview -The technical definition of an xpm package is _a folder which includes a +The technical definition of an xpm package is _a folder containing a package.json file with some minimal content_ -([full definition](../concepts)); -it does not require any special structure for the folders or for the -version-control system, if any. +(refer to the [Concepts](../concepts) page for further details). +This definition does not mandate any particular folders hierarchy +or version control system, if any. -Therefore, an xpm package can be created with any tool, and can be stored -in any version control system. - -The xPack project uses public GitHub repositories, and, for convenience, -recommends GitHub for new projects too. +Therefore, an xpm package can be created using any tool and stored in +any version control system. :::tip -As for the main development environment, for all xPack projects the editor -of choice is Visual Studio Code (VS Code), -but you can use -any editor you like; just be sure that on Windows it does not mess the -line terminators. +All xPack Project sub-projects are hosted in public **GitHub** repositories. +For convenience, it is recommended to create new projects on GitHub as well. ::: +:::tip + +For the main development environment, **Visual Studio Code** (VS Code) +is the preferred editor for all xPack projects. However, you may use +any editor you prefer; just ensure that on Windows, it does not alter +the line terminators. + +::: ## Recommended workflow -### Project content +### Project content considerations -From the package author's point of view, there can be packages with -**original content**, and packages with **3rd party content**. +From the package author's perspective, there can be packages with +**original content** and packages with **third-party content**. -These are generally projects created from scratch, and the package -author is the same as the content author. +Packages with original content are typically projects created from scratch, +where the package author is also the content author. - + -For projects with 3rd party content, the ideal case would be to convince the 3rd party project maintainer -to include the xPack -metadata (like the `package.json` file) -in the project and possibly publish the project on npmjs.com. +For projects with third-party content, the ideal scenario would be +to persuade the third-party project maintainer to include the xPack +metadata (such as the `package.json` file) in the project and possibly +publish it on npmjs.com. -Unfortunately this is rarely possible, and a more realistic approach is +Unfortunately, this is rarely feasible. A more realistic approach is to **fork the project** and add the required metadata. -This must be done carefully, since it may add some **maintenance burden** +This must be done carefully, as it may add some maintenance burden to keep them in sync with the originals. - ### The `xpack` branch and three-way merging -One way to reduce the maintenance burden of packages with 3rd party content -is to use the +One way to reduce the maintenance burden of packages with third-party content +is to use Git's [three-way merge](https://en.wikipedia.org/wiki/Merge_(version_control)#Three-way_merge) -feature of Git and a separate branch to accommodate the xPack specific changes. +feature and a separate branch to accommodate the xPack-specific changes. -This method does not require any changes to the original project, which can -keep its original structure, with its original branches, regardless -their names. +This method does not require any modifications to the original project, +which can retain its original structure and branches, regardless of their names. The only requirement is to create a new branch (preferably named `xpack`) -and to keep the changes on it; thus the main branch (probably `main` or `master`) can -easily track the upstream repository, while the xPack specific changes -continue to be developed using the `xpack` branch; from time to time the -`main` branch can be merged into the `xpack` branch and things kept in sync. +and to keep the changes on it. Thus the main branch (likely `main` or `master`) can +easily track the upstream repository, while the xPack-specific changes +continue to be developed using the `xpack` branch. From time to time, the +`main` branch can be merged into the `xpack` branch to keep everything in sync. :::info -The xPack tools do not require and -do not enforce the use of a branch named `xpack`, this is only -a recommendation. +The xPack tools do not require or enforce the use of a branch named `xpack`; +this is merely a recommendation. ::: -### Projects without a public Git repository + -An extra complication can be encountered with projects distributed only as -archives, without a public Git repository. + -For these projects it is recommended to reconstruct the history based on -existing archives. +If the third-party project has its upstream public repository hosted on GitHub, fork it. - +:::info - +If the project has a Git repository hosted on a different site, clone the project and save it to GitHub. -If the 3rd party project uses a public GitHub repository, fork it. For projects with Git repositories hosted in different sites, clone the project and save them to GitHub. +::: With the GitHub web interface: - select the upstream project -- fork it, for example in the - [3rd party xPacks](https://github.com/xpack-3rd-party) organization) +- fork it (for example in an organisation like the + [xpack-3rd-party](https://github.com/xpack-3rd-party)) - preferably rename it: - add a prefix with the name of the original organization - add the `-xpack` suffix @@ -140,7 +137,7 @@ With the GitHub web interface: - enable **Discussions**, Set up discussions - quit the **Settings** tab (there is no Save) -#### Clone locally +### Clone locally Clone the project locally on the development machine: @@ -152,7 +149,7 @@ With the GitHub web interface: - click Open with GitHub Desktop; save to a folder like `xpack-3rd-party/-xpack.git` -#### Identify the latest release +### Identify the latest release With VS Code, Fork or Git: @@ -165,41 +162,18 @@ With VS Code, Fork or Git: With VS Code, Fork or Git: - select the tagged commit -- create new branch `xpack` +- create a new `xpack` branch - switch to it - - - - -For projects distributed as archives, to simplify maintenance, -it is recommended to reconstruct the history in a separate branch -(like `originals`) by adding commits with the content of each released -archive. - -Follow the steps to create a new repository, and watch for the extra steps to -create the `originals` branch. - - - - - - +### Add the `LICENSE-XPACK` file -### Edit the `LICENSE[-XPACK]` file - -The automatically generated `LICENSE` file already includes the -user name as the copyright owner. When the project is owned by -an organisation, the name refers to the organisation. Probably -this is not exactly what you need, and you might prefer to have -your name in the copyright notice. - -Check and possibly adjust to match your `LICENSE` requirements. +The original project probably has its own LICENSE file. +Add a new file with the xPack specific license that covers the xPack metadata. ```text MIT License -Copyright (c) 2022 Liviu Ionescu +Copyright (c) 2022 Liviu Ionescu. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy ... @@ -207,43 +181,68 @@ Permission is hereby granted, free of charge, to any person obtaining a copy With VS Code, Fork or Git: -- for 3rd party content, rename it to `LICENSE-XPACK` +- copy locally a license file +- rename it to `LICENSE-XPACK` - stage the file -- commit with the following message: **LICENSE: update copyright owner** +- commit with the following message: **LICENSE-XPACK: update copyright owner** -### Create the `originals` branch + + + -For a 3rd party project that does not use a -public Git project, but is distributed only as release archives, to -keep track of the changes it is recommended to -recreate the Git with the original -code on a separate branch, like `originals`, and later treat it -as the `master` branch. +An additional complication can arise with projects distributed only as release +archives, without a public Git repository. + +For these projects, it is recommended to reconstruct the history based on +existing archives in a separate branch +(such as `originals`) by adding commits with the content of each released +archive. With each upstream release, while on the `originals` branch, -fully remove the content and extract the newly released archive. +fully remove the content extract the newly released archive, commit and push. +Then merge into `xpack`. + + -Then merge the update `originals` branch into the `xpack` branch. +### Create the `originals` branch + +With VS Code, Fork or Git: +- select the `xpack` branch +- create a new `originals` branch +- switch to it +- add the content of the original release archive. In case the archive contains binary files, or other large files considered not essential for the xPack distribution, add them to `.gitignore`. +- commit with a message like: **vX.Y.Z content** Add/Edit the README file to add: ```text -This branch is used to recreate the 3rd party project history +This branch is used to recreate the third-party project history from release archives. ``` -Commit with the following message: **README: notice for 3rd party content** +- commit with the following message: **README: notice for third-party content** +- push the `originals` branch + +### Merge original content into `xpack` +With VS Code, Fork or Git: + +- select the `xpack` branch +- merge the `originals` branch + -### Edit the `.gitignore` file + + + +### Edit/Add the `.gitignore` file With VS Code: @@ -389,9 +388,8 @@ Open `package.json` with VS Code: your npm organisations) and the project name, without `-xpack.git` (like `@micro-os-plus/diag-trace`, `@xpack-dev-tools/ninja-build`, `@xpack-3rd-party/arm-cmsis-core`) -- as **version**, enter `0.1.0` if the project is in early development, - or accept 1.0.0 for the first stable release; generally use the - [semver](https://semver.org) conventions +- as **version**, enter `0.1.0; generally use the + [SemVer](https://semver.org) conventions - as **description**, use the same string as the GitHub project description - in **scripts**, check and possibly remove a trailing comma, - as **url** and **homepage**, use the actual project Git URL @@ -402,13 +400,13 @@ Open `package.json` with VS Code: "author": { "name": "Liviu Ionescu", "email": "ilg@livius.net", - "url": "https://github.com/ilg-ul/" + "url": "https://github.com/ilg-ul" } } ``` - as **license**, enter the [SPDX](https://spdx.org/licenses/) license - identifier (like `MIT`); if the license is not a standard one, provide + identifier (e.g. `MIT`). If the license is not a standard one, provide the text in a `LICENSE` file and update the JSON to read: ```json @@ -439,16 +437,26 @@ Update the list of npm scripts: { "scripts": { "npm-install": "npm install", - "pack": "npm pack", - "version-patch": "npm version patch", - "version-minor": "npm version minor", + "npm-link": "npm link", + "npm-outdated": "npm outdated", + "npm-update": "npm update", + "npm-pack": "npm pack", + "npm-version-patch": "npm version patch", + "npm-version-minor": "npm version minor", "postversion": "git push origin --all && git push origin --tags", - "git-log": "git log --pretty='%cd * %h %s' --date=short" + "git-log": "git log --pretty='%cd * %h %s' --date=short",{% if isJavaScript == "true" %} }, - "...": "..." + ... } ``` +:::info + +Some of the above are merely for convenience when using VS Code, +as they can be performed with a simple mouse click. + +::: + ### Commit the initial package file With VS Code, Fork or Git: @@ -495,7 +503,7 @@ and close existing issues and pull requests. ## 2022-01-03 -* v2.0.5 +- v2.0.5 ``` With VS Code, Fork or Git: @@ -507,9 +515,8 @@ With VS Code, Fork or Git: Copy/paste files like: -- `CI.yml` -- `test-all.yml` - +- `test-ci.yml` (to be executed automatically opon pushes) +- `test-all.yml` (to be triggered manually upon user request) - commit with the following message: **.github/workflows preliminary content** For projects with an upstream Git, disable existing workflows. diff --git a/website/sidebar-docs-custom.ts b/website/sidebar-docs-custom.ts index 32407b6..eb564f5 100644 --- a/website/sidebar-docs-custom.ts +++ b/website/sidebar-docs-custom.ts @@ -58,6 +58,7 @@ export const customDocsSidebar = [ ] }, { + // Keep this in sync with /docs/guide sections. type: 'category', label: 'Package Author\'s Guide', link: {