diff --git a/website/docs/developer/index.mdx b/website/docs/developer/index.mdx index 913ec21..c1ebce9 100644 --- a/website/docs/developer/index.mdx +++ b/website/docs/developer/index.mdx @@ -186,14 +186,14 @@ xpm/xPack actions and build configurations are supported in Visual Studio via th With this extension installed, xpm/xPack actions can be very conveniently invoked via a single mouse click, for example: -![xPack actions](https://github.com/xpack/vscode-xpack-extension-ts/raw/master/assets/docs-images/xpack-actions.png) +![xpm actions](https://github.com/xpack/vscode-xpack-extension-ts/raw/master/assets/docs-images/xpack-actions.png) ## Prerequisites The build scripts run on GNU/Linux and macOS. The Windows binaries are -compiled on x64 GNU/Linux, using [mingw-w64](https://mingw-w64.org). +compiled on GNU/Linux, using [mingw-w64](https://mingw-w64.org). For details on installing the prerequisites, please read the [Build Prerequisites](https://xpack-dev-tools.github.io/docs/developer/install/prerequisites/) diff --git a/website/docs/maintainer/index.mdx b/website/docs/maintainer/index.mdx index 5c3280e..08c87ba 100644 --- a/website/docs/maintainer/index.mdx +++ b/website/docs/maintainer/index.mdx @@ -220,13 +220,6 @@ and fix them; assign them to a milestone (like {customField('xpackVersion' ### Update `CHANGELOG.md` -- open the `CHANGELOG.md` file -- check if all previous fixed issues are in -- check the latest commits `xpm run git-log`; if necessary, copy/paste lines, - group by dates and edit them using the below regular expressions -- add a new entry like _**\* v{customField('xpackVersion')} prepared**_ -- commit with a message like _**prepare v{customField('xpackVersion')}**_ - To turn the dates into headings, change from: ```txt @@ -257,6 +250,14 @@ to: * ``` +- open the `CHANGELOG.md` file +- check if all previous fixed issues are in +- check the latest commits `xpm run git-log`; if necessary, copy/paste lines, + group by dates and edit them using the below regular expressions +- add a new entry like _**\* v{customField('xpackVersion')} prepared**_ +- commit with the message _**prepare v{customField('xpackVersion')}**_ + + ### Push the changes to the `xpack-development` branch Be sure that the latest commit that updates `VERSION` is pushed @@ -430,7 +431,7 @@ via HomeBrew, and make a link to `/usr/local/bin`. ::: -- commit with _**website: update folder hierarchies**_. +Commit with the message _**website: update folder hierarchies**_. ### Update the list of links in top package.json @@ -439,14 +440,14 @@ sequence, for each platform (Windows, macOS, GNU/Linux), and check the differences compared to the repository. -Commit if necessary with _**package.json: update executables links**_ +Commit if necessary with the message _**package.json: update executables links**_. ### Update the durations of the development builds In `website/docs/maintainer/_development-durations.mdx`, update the durations of the builds. -Commit if necessary with _**website: update development durations**_ +Commit with the message _**website: update development durations**_. ### How to build a debug version @@ -537,7 +538,7 @@ to `"@xpack-dev-tools/xbb-helper":` ### Commit the changes to `build-assets/package.json` -Use the message **build-assets/package.json: bump deps**. +Commit with the message _**build-assets/package.json: bump deps**_. ### Check for disk space @@ -584,7 +585,7 @@ rm -rf ~/Work/xpack-dev-tools/*/build-assets/build ### Generate the GitHub workflows -Run the **generate-workflows** xPack action to update the +Run the **generate-workflows** xpm/xPack action to update the GitHub workflow files. ```sh @@ -593,7 +594,7 @@ xpm run generate-workflows -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build- ### Commit and push -- commit with the message **Re-generate workflows** +- commit with the message **re-generate workflows** - push the `xpack-development` branch to GitHub @@ -619,7 +620,7 @@ xpm run trigger-workflow-build-linux-arm64 -C ~/Work/xpack-dev-tools/qemu-riscv- xpm run trigger-workflow-build-linux-arm -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets ``` -The scripts behind these actions require the `XPACK_DEV_TOOLS_FG_DISPATCH_TOKEN` +The scripts behind these actions require the `GITHUB_API_DISPATCH_TOKEN` variable to be present in the environment, and the organization `PUBLISH_TOKEN` to be visible in the Settings → Action → @@ -638,6 +639,8 @@ The workflow results and logs are available from the Update the values in `website/docs/maintainer/_github-actions-durations.mdx` with those shown by GitHub Actions. +Commit with the message _**website: update actions durations**_. + The resulting binaries are available for testing from [pre-releases/test](https://github.com/xpack-dev-tools/pre-releases/releases/tag/test/). @@ -661,13 +664,20 @@ xpm run trigger-workflow-test-docker-linux-x64 -C ~/Work/xpack-dev-tools/qemu-ri xpm run trigger-workflow-test-docker-linux-arm -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets ``` -The scripts behind these accessible require the `XPACK_DEV_TOOLS_FG_DISPATCH_TOKEN` variable to be present +The scripts behind these accessible require the `GITHUB_API_DISPATCH_TOKEN` variable to be present in the environment. These actions use the `xpack-development` branch of this repo and the [pre-releases/test](https://github.com/xpack-dev-tools/pre-releases/releases/tag/test/) binaries. +:::caution + +Some of the `docker-linux-arm` tests have an issue on Debian and the +**Clean working area** step fails. + +::: + The tests results are available from the [GitHub Actions](https://github.com/xpack-dev-tools/qemu-riscv-xpack/actions/) page. @@ -679,7 +689,7 @@ with previous runs. Since GitHub Actions provides a limited range of versions for the macOS runner, the multi-version macOS tests run on Travis. -To trigger the Travis test, run the **trigger-travis-macos** xPack action: +To trigger the Travis test, run the **trigger-travis-macos** xpm/xPack action: ```sh xpm run trigger-travis-macos -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets @@ -721,10 +731,10 @@ xattr -cr ${HOME}/Downloads/xpack-* - in `CHANGELOG.md`, add the release date and a message like _**\* v{customField('xpackVersion')} released**_ -- commit with _**CHANGELOG update**_ +- commit with the message _**CHANGELOG update**_ - check and possibly update the `build-assets/templates/body-github-release-liquid.mdx` - push the `xpack-development` branch to GitHub -- run the **trigger-workflow-publish-release** xPack action: +- run the **trigger-workflow-publish-release** xpm/xPack action: ```sh xpm run trigger-workflow-publish-release -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets @@ -745,13 +755,17 @@ with all binaries attached. - do **not** enable Discussions yet - click the **Publish release** button -Note: at this moment the system should send a notification to all clients -watching this project. +:::info + +At this moment the system should send an email notification to all clients +watching the qemu-riscv-xpack project. + +::: ### Prepare a new blog post - check and possibly update the `website/blog/_templates/blog-post-release-part-[12]-liquid.md` -- run the **generate-website-blog-post** xPack action; +- run the **generate-website-blog-post** xpm/xPack action; this will add a file in the `website/blog` folder: ```sh @@ -760,18 +774,18 @@ xpm run generate-website-blog-post -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.gi - edit the front matter properties - select the correct summary -- commit with _**blog post release {customField('xpackVersion')} published**_ +- commit with the message _**website: blog post release {customField('xpackVersion')} published**_ ### Update the web install page - check and possibly update the output of the `--version` runs in - `website/docs/install/_automatic-install-quick-test.mdx` - `website/docs/install/_manual-install-quick-test.mdx` -- commit changes +- commit with the message _**website: update quick tests**_ ### Check the list of links in top package.json -- open the `package.json` file +- open the top `package.json` file - check if the links in the `bin` property cover the actual binaries - if necessary, also check on Windows @@ -779,7 +793,7 @@ xpm run generate-website-blog-post -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.gi - select the `xpack-development` branch - be sure that the binaries were attached to the pre-release -- run the **update-package-binaries** xPack action: +- run the **update-package-binaries** xpm/xPack action: ```sh xpm run update-package-binaries -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets @@ -791,7 +805,7 @@ xpm run update-package-binaries -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/b - from the release, check the SHA & file names - compare the SHA sums with those shown by `cat *.sha` - check the executable names -- commit all changes, use a message like +- commit all changes with the message _**package.json: update urls for {customField('xpackVersion')}.{customField('npmSubversion')} release**_ ### Publish on the npmjs.com server @@ -799,7 +813,7 @@ xpm run update-package-binaries -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/b - select the `xpack-development` branch - check the latest commits `xpm run git-log` - update `CHANGELOG.md`, add a line like _**\* v{customField('xpackVersion')} published on npmjs.com**_ -- commit with a message like _**CHANGELOG: publish npm v{customField('xpackVersion')}.{customField('npmSubversion')}**_ +- commit with the message _**CHANGELOG: publish npm v{customField('xpackVersion')}.{customField('npmSubversion')}**_ - `npm pack` and check the content of the archive, which should list only the `package.json`, the `README.md`, `LICENSE` and `CHANGELOG.md`; possibly adjust `.npmignore` @@ -829,7 +843,7 @@ After a few moments the version will be visible at ### Test if the binaries can be installed with xpm -Run the **trigger-workflow-test-xpm** xPack action: +Run the **trigger-workflow-test-xpm** xpm/xPack action: ```sh xpm run trigger-workflow-test-xpm -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets @@ -846,10 +860,14 @@ The tests results are available from the When the release is considered stable, promote it as `latest`: + { +`npm dist-tag add @xpack-dev-tools/qemu-riscv@${customField('xpackVersion')}.${customField('npmSubversion')} latest +`} + +Check the result: + { `npm dist-tag ls @xpack-dev-tools/qemu-riscv -npm dist-tag add @xpack-dev-tools/qemu-riscv@${customField('xpackVersion')}.${customField('npmSubversion')} latest -npm dist-tag ls @xpack-dev-tools/qemu-riscv `} In case the release proves problematic and needs to be unpublished: @@ -863,23 +881,26 @@ In case the release proves problematic and needs to be unpublished: Validate the web site content in a local build via the npm `build` script: ```sh -npm --prefix website run build +npm run build -C website ``` ### Publish the website +- stop the local web server +- select the `website` branch - merge `xpack-development` into `website` - push the `website` branch to GitHub - -At this moment an automated GitHub Action will generate and publish the website. - + :::info + At this moment an automated GitHub Action will generate and publish the website. + ::: - the new release blog post is in https://xpack-dev-tools.github.io/qemu-riscv-xpack/blog/ - remember the post URL, since it must be used to update the release page and the X/Twitter announcement +- switch to https://xpack-dev-tools.github.io/qemu-riscv-xpack/docs/maintainer/#update-the-xpack-branch The `website` branch may be subsequently updated, as long as the -version in `package.json` is not changed. +version in the top `package.json` is not changed. ### Update the `xpack` branch @@ -901,7 +922,8 @@ Avoid further updates to the `xpack` branch until the next release. - check the download counter, it should match the number of tests - add a link to the Web blog `[Continue reading »]()`; use an same blog URL - remove the _tests only_ notice -- **disable** the **pre-release** button +- **disable** the **Set as a pre-release** button +- **enable** the **Set as the latest release** button - click the **Update Release** button ### Check SourceForge mirror @@ -917,7 +939,7 @@ Avoid further updates to the `xpack` branch until the next release. ### Clean the work area -Run the **trigger-workflow-deep-clean** xPack action +Run the **trigger-workflow-deep-clean** xpm/xPack action ```sh xpm run trigger-workflow-deep-clean -C ~/Work/xpack-dev-tools/qemu-riscv-xpack.git/build-assets @@ -928,6 +950,15 @@ This will remove the build folders on all self-hosted runners. The results are available from the [GitHub Actions](https://github.com/xpack-dev-tools/qemu-riscv-xpack/actions/) page. +### Close possible open issues + +Check GitHub issues and pull requests: + +- https://github.com/xpack-dev-tools/qemu-riscv-xpack/issues +- https://github.com/xpack-dev-tools/qemu-riscv-xpack/pulls + +Close those that were addressed. + ## Share on Twitter - in a separate browser windows, open [X/Twitter](https://twitter.com) diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 080c84e..dd8597c 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -335,19 +335,29 @@ const config: Config = { 'aria-label': 'GitHub repository', }, { - label: `v${customFields.xpackVersion}`, - position: 'right', - href: `https://github.com/xpack-dev-tools/qemu-riscv-xpack/releases/tag/v${customFields.xpackVersion}`, - }, - { - href: 'https://github.com/xpack-dev-tools/', - label: 'xpack-dev-tools', + type: 'dropdown', + href: 'https://github.com/xpack-dev-tools/qemu-riscv-xpack/', position: 'right', + label: 'GitHub', + items: [ + { + label: `qemu-riscv-xpack`, + href: `https://github.com/xpack-dev-tools/qemu-riscv-xpack/`, + }, + { + label: 'xpack-dev-tools org', + href: 'https://github.com/xpack-dev-tools/', + }, + { + label: 'xpack org', + href: 'https://github.com/xpack/', + }, + ] }, { - href: 'https://github.com/xpack/', - label: 'xpack', + label: `${customFields.xpackVersion}`, position: 'right', + href: `https://github.com/xpack-dev-tools/qemu-riscv-xpack/releases/tag/v${customFields.xpackVersion}`, }, ], }, @@ -408,11 +418,11 @@ const config: Config = { href: 'https://github.com/xpack-dev-tools/qemu-riscv-xpack/', }, { - label: 'GitHub xpack-dev-tools', + label: 'GitHub xpack-dev-tools org', href: 'https://github.com/xpack-dev-tools/', }, { - label: 'GitHub xpack', + label: 'GitHub xpack org', href: 'https://github.com/xpack/', }, ],