Skip to main content
note

Work in progress.

How to create a new xPack GitHub repository

Overview​

The technical definition of an xpm package is a folder containing a package.json file with some minimal content (refer to the 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 using any tool and stored in any version control system.

tip

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.

Project content considerations​

From the package author's perspective, there can be packages with original content and packages with third-party content.

Packages with original content are typically projects created from scratch, where the package author is also the content author.

Create the GitHub project​

With a browser, at GitHub, select your account or organisation. (for the purposes of this project, the organisations that use xPacks are: xPacks Dev Tools, µOS++, 3rd party source xPacks).

  • click the green New button to create a new repository

    • enter Repository name; use all lowercase and hyphens to separate words (not underscores!); preferably suffix the name with -xpack
    tip

    To easily identify the project as an xPack, it is recommended to suffix the project name with '-xpack'.

    • enter Description (like A source library package with ... or A binary package with ...; no ending dot!)
    • select Public
    • enable Initialize this repository with a README
    • select Add .gitignore: Node
    • select Add a license: MIT License; this is the license of choice for xpm packages, but any other license of your choice is also ok
    • click the Create Repository button

  • select the Settings tab

    • in the Features section
      • disable Wikis
      • enable Sponsorship (if needed)
      • disable Projects
      • enable Discussions
    • quit the Settings tab (there is no Save)

Clone the repository to a local folder​

With the GitHub web interface:

  • open the project
  • select the Code tab
  • click the Clone or download button; this will open a small Clone to HTTPS window
  • click the Copy icon, or explicitly copy the URL
  • in a terminal window, in a place of our choice, create a folder to store all xPacks (for example it can be named xPacks):
mkdir -p xPacks
cd xPacks
git clone https://github.com/<user>/<project>.git <project>.git

Edit the master README.md file​

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 inform users about this configuration, edit the README.md file. Retain the header line and replace the content with:

This project does not use the `master` branch, please
switch to the `xpack` branch to access the project files.

With VS Code, Fork or Git:

  • stage the README.md file
  • commit with the following message: README: 'no master' notice

Edit the LICENSE file​

The automatically generated LICENSE file already includes the 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.

For example, xPack projects use:

MIT License

Copyright (c) 2024 Liviu Ionescu. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
...

With VS Code, Fork or Git:

  • stage the file
  • commit with the following message: LICENSE: update copyright owner

Create the xpack branch​

With VS Code, Fork or Git:

  • select the master branch
  • create a new xpack branch
  • switch to it
  • push the xpack branch

Edit/Add the .gitignore file​

With VS Code:

  • add the following to .gitignore:

# added for xPack

.vscode/c_cpp_properties.json

# xpm
xpacks/
build*/

/*.tgz

# Windows
Thumbs.db

# macOS
.DS_Store

# end
  • for Eclipse C/C++ projects you can include:
# Eclipse
.settings/
Debug/
Release/

With VS Code, Fork or Git:

  • stage the .gitignore file
  • commit with the following message: .gitignore: add xPack specifics

Add the .npmignore file​

With VS Code, create a new file with:


.DS_Store
.git/
.github/
.gitignore
.gitmodules
.clang-*
.cmake-format

.vscode/

patches/
pkgconfig/
scripts/
test*/
build*/
ci/
docs/
example*/

xpacks/
node_modules/

/*.tgz

README-*
LICENSE-*
CONTRIBUTING**
  • update the content until npm pack shows only the desired content
  • stage the .npmignore file
  • commit with the following message: .npmignore preliminary content

Publish all branches​

With VS Code, Fork or Git:

  • push all local branches (master, xpack and maybe the originals)

Change the default branch to xpack​

With the GitHub web interface:

  • open the project
  • select the Settings tab
  • select the Branches grouping
  • change the Default branch to xpack
  • click the Update button
  • click the I understand, update the default branch confirmation window

Create the npm/xpm package.json​

Select the xpack branch.

Use xpm init and later edit the package.json.

$ cd <project>.git
$ xpm init --verbose
$ cat package.json
{
  "name": "@<scope>/<project-name>",
  "version": "0.1.0",
  "description": "A source/binary xPack with <your-description-here>",
  "main": "",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/<user-id>/<project-name>-xpack.git"
  },
  "bugs": {
    "url": "https://github.com/<user-id>/<project-name>-xpack/issues"
  },
  "homepage": "https://github.com/<user-id>/<project-name>-xpack",
  "keywords": [
    "xpack"
  ],
  "author": {
    "name": "<author-name>",
    "email": "<author-email>",
    "url": "<author-url>"
  },
  "license": "MIT",
  "config": {},
  "dependencies": {},
  "devDependencies": {},
  "xpack": {}
}
$

Open package.json with VS Code:

  • as name enter the scope (your npm account name or one of 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; generally use the SemVer 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
  • as author, enter full data, like
{
  "author": {
    "name": "Liviu Ionescu",
    "email": "ilg@livius.net",
    "url": "https://github.com/ilg-ul"
  }
}
  • as license, enter the SPDX license 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:
{ "license": "SEE LICENSE IN <filename>" }
  • if the package is inspired by other existing code, enter the author as the first contributor, for example:
{
  "contributors": [
    {
      "name": "SEGGER Microcontroller GmbH & Co. KG",
      "email": "support@segger.com",
      "url": "https://www.segger.com/",
      "git": "https://github.com/boost-ext/ut.git",
      "license": "..."
    }
  ],
  "...": "..."
}

Update the list of npm scripts:

{
  "scripts": {
    "npm-install": "npm install",
    "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",{% 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:

  • stage the package.json
  • commit with the following message: package.json: v0.1.0

Edit the README.md file with actual content​

With the editor of your choice:

  • start with some badges
  • as headers, you can start with H1, the npmjs server now shows it
  • after the main title, copy the project description
  • explain how to install the xPack (like xpm install --global @scope/name)
  • in the License section, use something like
### License

The original content is released under the
[MIT License](https://opensource.org/licenses/MIT), with all rights reserved to
[Liviu Ionescu](https://github.com/ilg-ul/).

With VS Code, Fork or Git:

  • stage the README*.md files
  • commit with the following message: README: preliminary content

Add a CHANGELOG[-XPACK].md file​

A possible content:

# Change & release log

Releases in reverse chronological order.

Please check
[GitHub](https://github.com/micro-os-plus/micro-test-plus-xpack/issues/)
and close existing issues and pull requests.

## 2022-01-03

- v2.0.5

With VS Code, Fork or Git:

  • stage the CHANGELOG.md files
  • commit with the following message: CHANGELOG: preliminary content

Add .github/workflows/*​

Copy/paste files like:

  • 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.

Publish the initial version to GitHub​

With VS Code, Fork or Git:

  • click the Push button (to push the xpack branch to the server)

Add more content​

  • add project files
  • copy/paste the tests[-xpack] folder

Commit the initial content​

With VS Code, Fork or Git:

  • stage the new files
  • commit with the following message: add initial content

Create the xpack-development branch​

With VS Code, Fork or Git:

  • select the xpack branch
  • create the xpack-development branch

Generally work in the xpack-development branch and only when ready merge it to master.

Publish the branches to GitHub​

With VS Code, Fork or Git:

  • Push all branches (or at least xpack and xpack-development)

Publish the initial version to the npmjs public registry​

  • check the latest commits npm run git-log
  • update CHANGELOG.md; commit with a message like CHANGELOG: prepare npm v1.10.0-1.1
  • npm version v1.10.0-1.1; the first 4 numbers are the same as the GitHub release; the fifth number is the npm specific version
  • npm pack and check the content of the archive, which should list only the desired content and the package.json, the README.md, LICENSE and CHANGELOG.md files
  • push all changes to GitHub
  • npm publish --access public --tag next

When the release is considered stable, promote it as latest. For example:

  • npm dist-tag ls @xpack-dev-tools/ninja-build
  • npm dist-tag add @xpack-dev-tools/ninja-build@1.10.0-1.1 latest
  • npm dist-tag ls @xpack-dev-tools/ninja-build

Bump version​

In general, depending on the disruption degree, chose one of the following:

cd <project>.git
npm version patch
npm version minor
npm version major

With VS Code, Fork or Git:

  • Push the commits