From 347775a56de12cc586b9ba2a0d0249ef898de81f Mon Sep 17 00:00:00 2001 From: Lukas Hirt Date: Tue, 10 Nov 2026 13:22:33 +0100 Subject: [PATCH 1/2] docs(ocis): rewrite web releasing docs for the oCIS monorepo The Web releasing guide still described releases of the standalone owncloud/web repository. Following it in the oCIS monorepo would push a bare v tag, which triggers the oCIS release workflow, and move all of oCIS's unreleased changelog entries. Rewrite it to describe how Web is released with oCIS, how changelog entries and translations are handled, and how the Web npm packages are published via -v tags. Replace the obsolete web service releasing page (WEB_ASSETS_VERSION, .drone.env) with how the web service embeds the Web build, and point the removed getToken getter to its Pinia replacement. Refs: OCISDEV-1648 Signed-off-by: Lukas Hirt --- .../clients/web/releasing/deprecations.adoc | 2 +- .../pages/clients/web/releasing/index.adoc | 4 +- .../clients/web/releasing/releasing.adoc | 168 +++++++----------- .../pages/services/s-list/web/releasing.adoc | 34 ++-- 4 files changed, 82 insertions(+), 126 deletions(-) diff --git a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc index 2e179fe7..5117cf82 100644 --- a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc +++ b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc @@ -131,7 +131,7 @@ The following features *are already removed*. | `getToken` getter | v6 | July 7, 2022 -| Use `runtime/auth/accessToken` getter +| Use `runtime/auth/accessToken` getter. Since the removal of the Vuex store (v9), use `accessToken` of `useAuthStore()` from `@ownclouders/web-pkg` instead | N/A | `user` state is not supposed to deal with authentication details. We introduced the namespaced `auth` module for `user` and `public-link` related authentication contexts |=== diff --git a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/index.adoc b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/index.adoc index 6a8f8e80..09cf851f 100644 --- a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/index.adoc +++ b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/index.adoc @@ -1,6 +1,6 @@ = Releasing :toc: right :toclevels: 3 -:description: This section serves as a guide for releasing ownCloud Web and managing important deprecations for a release. +:description: This section describes how ownCloud Web changes are released with oCIS, how the Web npm packages are published, and which deprecations to consider. -This section serves as a guide for releasing ownCloud Web and managing important deprecations for a release. +This section describes how ownCloud Web changes are released with oCIS, how the Web npm packages are published, and which deprecations to consider. diff --git a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc index ad4af89c..c5418460 100644 --- a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc +++ b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc @@ -1,137 +1,97 @@ = Releasing :toc: right :toclevels: 3 -:description: ownCloud Web can be hosted standalone for a dedicated oCIS backend or bundled as part of oCIS. +:description: ownCloud Web is part of the oCIS monorepo and is released together with oCIS. Only the npm packages are published separately. -== Releasing ownCloud Web +== Web Is Released With oCIS -ownCloud Web can be hosted standalone for a dedicated oCIS backend or bundled as part of oCIS. +ownCloud Web lives in the `web/` folder of the link:https://github.com/owncloud/ocis[oCIS repository]. It is not released on its own: the `web` service build runs `pnpm install && pnpm check:types && pnpm build` in `web/` and copies the result into the service assets, so every oCIS release ships the Web version of the commit it was built from. -=== Versioning +There are no separate Web releases, Web versions or Web release branches. Web changes reach a release the same way as any other oCIS change, through `master` and the oCIS `stable-X.Y` branches. See the xref:release_life_cycle.adoc[oCIS release life cycle] for release types and schedule, and the xref:releasing_guide/releasing_guide.adoc[Releasing Guide] for the oCIS release process. -We follow the link:https://semver.org/[Semantic Versioning] scheme. Therefore, each change is of one of the possible types: `Bugfix, Change, Enhancement, Security`. +== Changelog Entries -The highest type before a new release determines the version update number, so if it's only `Bugfix` and `Security` changes the next release will be a `PATCH` version bump, if there's at least one `Enhancement` within the changes this leads to a `MINOR` version bump, while `Change` type changes make for a new `MAJOR` release version. +For a user-facing Web change, add a changelog entry to the oCIS root `changelog/unreleased/` folder, based on `changelog/TEMPLATE`: -=== Release Guide +* The first line starts with the change type `Bugfix`, `Change` (breaking change), `Enhancement` (new feature) or `Security`, followed by a short title. +* The body describes the change, wrapped at 80 characters. +* The last section lists the PR and issue URLs, for example `+https://github.com/owncloud/ocis/pull/+`. -==== Releasing a New Major Version +Existing Web entries are named like `bugfix-web-embed-delegated-token-renewal.md` or `enhancement-web-bump-pinia.md`. Do not create or move versioned changelog folders, this is part of the oCIS release process. -. Checkout the latest `stable-$major` branch + -This branch will be used as the base for the new major version branch. + -Replace `$major` with the *last* released major version. +In addition, PR titles follow link:https://www.conventionalcommits.org[Conventional Commits] as described in `COMMIT_CONVENTION.md`. Web changes usually use `web` as the scope, for example `fix(web): [OCISDEV-1572] show an error when a copy gets no answer`. PRs are squash-merged and release notes are generated from these titles with git-cliff. -. Create a new branch `stable-$major`. + -Replace `$major` with the *new* major version. +== Translations -. Push the newly created `stable-$major` branch +Web translations are synced with Transifex automatically by the nightly `Translation Sync` workflow (job `sync-web`), which opens a pull request with the updated translations. To update them manually, run the following from the `web/` folder: -. Create and checkout a new branch `chore/bump-version-$major.$minor.$patch` using the branch from previous step as base + -Replace `$major`, `$minor` and `$patch` with the new version. +[source,bash] +---- +make l10n-pull # pull the latest translations from Transifex +make l10n-write # write them to the translations.json files +---- -. Cherry pick all required changes from `master` into the current branch +== Publishing the npm Packages -. Create a new sub-folder in the `/changelog/` folder using the release version and current date `mkdir $major.$minor.$patch_$YYYY-MM-DD` + -Replace `$major`, `$minor` and `$patch` with the new version and `$YYYY-MM-DD` with the current date in the format `YYYY-MM-DD`. +The following packages in `web/packages/` are published to npm individually. Each one has its own version in its `package.json`, the versions are not kept in sync. -. Move all changelog items from the `/changelog/unreleased/` folder into the `$major.$minor.$patch_$YYYY-MM-DD` folder created in the previous step +[cols="1,2",options="header"] +|=== +| Package Folder +| npm Package -. Run `make l10n-pull` to pull the translations + -This command will pull the latest translations from Transifex into the current branch and saves them in the `/packages/*/l10n/` folders. +| `babel-preset` +| `@ownclouders/babel-preset` -. Run `make l10n-write` to write the translations + -This command will use translations pulled in the previous step and writes them to the `/packages/*/l10n/translations.json` files. +| `design-system` +| `@ownclouders/design-system` -. Run `./dev/scripts/bump_versions.sh $major.$minor.$patch`. + -This script will bump the `package.json` files in all relevant packages and the sonar cloud project version + -Replace `$major`, `$minor` and `$patch` with the new version. +| `eslint-config` +| `@ownclouders/eslint-config` -. Commit and push your changes. +| `extension-sdk` +| `@ownclouders/extension-sdk` -. Create a PR with tag `[full-ci]` in the title at the beginning to merge the `chore/bump-version-$major.$minor.$patch` branch into the new `stable-$major` branch +| `prettier-config` +| `@ownclouders/prettier-config` -. After merging, checkout the new `stable-$major` branch again +| `tsconfig` +| `@ownclouders/tsconfig` -. Run `./dev/scripts/create_and_push_tags.sh` + -This script will create and push tags for the main app as well as all packages that need to be released +| `web-client` +| `@ownclouders/web-client` -. The GitHub release will be created automatically together with the release artifacts +| `web-pkg` +| `@ownclouders/web-pkg` -==== Releasing a New Minor or Patch Version +| `web-test-helpers` +| `@ownclouders/web-test-helpers` +|=== -. Checkout the latest `stable-$major` branch + -This branch will be used as the base for the bump version branch. + -Replace the `$major` with the last released major version. +To publish a new version of a package: -. Create a new branch `chore/bump-version-$major.$minor.$patch` + -Replace `$major`, `$minor` and `$patch` with the new version. +. Bump the `version` in `web/packages//package.json` and merge it into `master` with a regular PR. -. Cherry pick all required changes from `master` into the current branch +. Create a signed, annotated tag `-v` on the merged commit and push it to `owncloud/ocis`: ++ +[source,bash] +---- +git tag -s -a web-pkg-v13.0.1 -m "web-pkg-v13.0.1" +git push origin web-pkg-v13.0.1 +---- -. Create a new sub-folder in the `/changelog/` folder using the release version and current date `mkdir $major.$minor.$patch_$YYYY-MM-DD` + -Replace `$major`, `$minor` and `$patch` with the new version and `$YYYY-MM-DD` with the current date in the format `YYYY-MM-DD`. +. The `Release NPM packages` workflow (`.github/workflows/release-npm-packages.yml`) picks up the tag and: ++ +* determines the package from the tag prefix and fails for an unknown prefix, +* fails if the version in the tag does not match the `version` in the package's `package.json`, +* builds the design tokens and, for `design-system`, `web-client`, `web-pkg` and `web-test-helpers`, the package itself, +* publishes the package with `pnpm publish --access public --tag latest`, authenticating with the job's GitHub OIDC token (`id-token: write`). No npm token is configured in the workflow. -. Move all changelog items from the `/changelog/unreleased/` folder into the `$major.$minor.$patch_$YYYY-MM-DD` folder created in previous step +Every publish sets the `latest` dist-tag, so the version just published becomes `latest`. -. Run `make l10n-pull` to pull the translations + -This command will pull the latest translations from Transifex into the current branch and saves them in the `/packages/*/l10n/` folders. +[WARNING] +==== +Never push a bare `v*` tag (for example `v12.5.0`) for Web. Any `v*` tag triggers the oCIS release workflow (`.github/workflows/release.yml`), which builds and publishes an oCIS release with that version. -. Run `make l10n-write` to write the translations + -This command will use translations pulled in previous step and writes them to the `/packages/*/l10n/translations.json` files. - -. Run `./dev/scripts/bump_versions.sh $major.$minor.$patch`. + -This script will bump the `package.json` files in all relevant packages and the sonar cloud project version + -Replace the `$major`, `$minor` and `$patch` with the new version. - -. Commit and push your changes. - -. Create a PR with tag `[full-ci]` in the title at the beginning to merge the `chore/bump-version-$major.$minor.$patch` branch into the latest `stable-$major` branch - -. After merging, checkout the latest `stable-$major` branch again - -. Run `./dev/scripts/create_and_push_tags.sh` + -This script will create and push tags for the main app as well as all packages that need to be released - -. The GitHub release will be created automatically together with the release artifacts - -==== Backporting Bug/Security Fixes Into Older Versions - -. Checkout the target `stable-$major` branch + -This branch will be used as the base for the new minor version branch. + -Replace `$major` with the target released major version. - -. Create a new branch `stable-$major.$minor`. + -Replace the `$major` and `$minor` with the new version. - -. Push the newly created `stable-$major.$minor` branch - -. Create a new branch `chore/bump-version-$major.$minor.$patch` using the branch from previous step as base + -Replace the `$major`, `$minor` and `$patch` with the new version. - -. Cherry pick all required changes from `master` into the current branch - -. Create a new sub-folder in the `/changelog/` folder using the release version and current date `mkdir $major.$minor.$patch_$YYYY-MM-DD` + -Replace the `$major`, `$minor` and `$patch` with the new version and `$YYYY-MM-DD` with the current date in the format `YYYY-MM-DD`. - -. Move all changelog items from the `/changelog/unreleased/` folder into the `$major.$minor.$patch_$YYYY-MM-DD` folder created in previous step - -. Run `make l10n-pull` to pull the translations + -This command will pull the latest translations from Transifex into the current branch and saves them in the `/packages/*/l10n/` folders. - -. Run `make l10n-write` to write the translations + -This command will use translations pulled in previous step and writes them to the `/packages/*/l10n/translations.json` files. - -. Run `./dev/scripts/bump_versions.sh $major.$minor.$patch`. + -This script will bump the `package.json` files in all relevant packages and the sonar cloud project version + -Replace `$major`, `$minor` and `$patch` with the new version. - -. Commit and push your changes. - -. Create a PR with tag `[full-ci]` in the title at the beginning to merge the `chore/bump-version-$major.$minor.$patch` branch into the new `stable-$major.$minor` branch - -. After merging, checkout the new `stable-$major.$minor` branch again - -. Run `./dev/scripts/create_and_push_tags.sh` + -This script will create and push tags for the main app as well as all packages that need to be released - -. The GitHub release will be created automatically together with the release artifacts +Do not use `web/dev/scripts/create_and_push_tags.sh` or `web/dev/scripts/bump_versions.sh`. They are leftovers from the standalone Web repository: the first one pushes such a bare `v` tag, the second one assumes that all packages share a single version. +==== diff --git a/content/ocis/9.0/modules/developer/pages/services/s-list/web/releasing.adoc b/content/ocis/9.0/modules/developer/pages/services/s-list/web/releasing.adoc index b472b3d7..74a3bb69 100644 --- a/content/ocis/9.0/modules/developer/pages/services/s-list/web/releasing.adoc +++ b/content/ocis/9.0/modules/developer/pages/services/s-list/web/releasing.adoc @@ -1,31 +1,27 @@ = Releasing :toc: right :toclevels: 3 -:description: The next generation Web Frontend is shipped as an oCIS Extension. +:description: The Web frontend is part of the oCIS repository and is built into the web service, so it is released together with oCIS. == Releasing -The next generation Web Frontend is shipped as an oCIS Extension. The `ocis-web` extension is also embedded in the single binary and part of the `ocis server` command. +The source code of ownCloud Web lives in the link:https://github.com/owncloud/ocis/tree/master/web[web folder] of the oCIS repository. There is no separate Web release that needs to be pulled into oCIS: every oCIS build compiles the Web frontend from the same commit and embeds it into the `web` service, which is part of the single binary and the `ocis server` command. -To update this package within all the deliveries, we need to update the package in the following chain from the bottom to the top. +=== How Web Gets Into the Web Service -=== Package Hierarchy +The `build-assets` target in `services/web/Makefile` builds the frontend and copies the result into the service assets (excerpt, `WEB_DIR` is `../../web`): -* link:https://github.com/owncloud/ocis[ocis] -** link:https://github.com/owncloud/ocis/tree/master/web[ocis-web] -*** link:https://github.com/owncloud/ocis/tree/master/ocis-pkg[ocis-pkg] -*** link:https://github.com/owncloud/web[ownCloud Web] +[source,make] +---- +build-assets: + cd $(WEB_DIR) && pnpm install && pnpm check:types && pnpm build + cp $(WEB_DIR)/config/config.json.dist $(WEB_DIR)/dist/ + cp -r $(WEB_DIR)/dist/. assets/core/ +---- -==== Prerequisites +CI runs this target as part of `ci-node-generate`. Changes to Web are therefore released with the next oCIS release of the branch they are merged into. -Before updating the assets, make sure that link:https://github.com/owncloud/web[ownCloud Web] has been released first and take note of its release tag name. +=== Further Information -==== Updating ocis-web - -. Create a branch `update-web-$version` in the link:https://github.com/owncloud/ocis[ocis repository] -. Change into web package folder via `cd web` -. Inside the `web/` folder, update the `Makefile` so that the WEB_ASSETS_VERSION variable references the currently released version of https://github.com/owncloud/web -. Move to the changelog (`cd ../changelog/`) and add a changelog file to the `unreleased/` folder (You can copy an old web release changelog item as a template) -. Move to the repo root (`cd ..`) and update the WEB_COMMITID in the `/.drone.env` file to the commit id from the released version (unless the existing commit id is already newer) -. _Optional:_ Test the changes locally by running `cd ocis && go run cmd/ocis/main.go server`, visiting link:https://localhost:9200[https://localhost:9200] and confirming everything renders correctly -. Commit your changes, push them and link:https://github.com/owncloud/ocis/pulls[create a PR] +* For changelog entries, translations and publishing the Web npm packages, see the xref:clients/web/releasing/releasing.adoc[Web releasing guide]. +* For the oCIS release process itself, see the xref:releasing_guide/releasing_guide.adoc[Releasing Guide] and the xref:release_life_cycle.adoc[Release Life Cycle]. From 23933906f673063e4cbf37647d9bd8eb8be49eec Mon Sep 17 00:00:00 2001 From: Lukas Hirt Date: Fri, 20 Nov 2026 15:07:50 +0100 Subject: [PATCH 2/2] docs(ocis): clarify web release notes source and package versions Release notes come from the changelog/ entries via calens; git-cliff is not wired into a release workflow yet. Note that only the npm packages carry their own versions, and lead the getToken deprecation row with the Pinia replacement. Signed-off-by: Lukas Hirt --- .../developer/pages/clients/web/releasing/deprecations.adoc | 2 +- .../developer/pages/clients/web/releasing/releasing.adoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc index 5117cf82..58b069ec 100644 --- a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc +++ b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/deprecations.adoc @@ -131,7 +131,7 @@ The following features *are already removed*. | `getToken` getter | v6 | July 7, 2022 -| Use `runtime/auth/accessToken` getter. Since the removal of the Vuex store (v9), use `accessToken` of `useAuthStore()` from `@ownclouders/web-pkg` instead +| Use `accessToken` of `useAuthStore()` from `@ownclouders/web-pkg`. The original replacement, the `runtime/auth/accessToken` getter, was removed together with the Vuex store in v9 | N/A | `user` state is not supposed to deal with authentication details. We introduced the namespaced `auth` module for `user` and `public-link` related authentication contexts |=== diff --git a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc index c5418460..f8f5e7e4 100644 --- a/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc +++ b/content/ocis/9.0/modules/developer/pages/clients/web/releasing/releasing.adoc @@ -7,11 +7,11 @@ ownCloud Web lives in the `web/` folder of the link:https://github.com/owncloud/ocis[oCIS repository]. It is not released on its own: the `web` service build runs `pnpm install && pnpm check:types && pnpm build` in `web/` and copies the result into the service assets, so every oCIS release ships the Web version of the commit it was built from. -There are no separate Web releases, Web versions or Web release branches. Web changes reach a release the same way as any other oCIS change, through `master` and the oCIS `stable-X.Y` branches. See the xref:release_life_cycle.adoc[oCIS release life cycle] for release types and schedule, and the xref:releasing_guide/releasing_guide.adoc[Releasing Guide] for the oCIS release process. +There are no separate Web releases, Web versions or Web release branches. Only the npm packages described <> have versions of their own. Web changes reach a release the same way as any other oCIS change, through `master` and the oCIS `stable-X.Y` branches. See the xref:release_life_cycle.adoc[oCIS release life cycle] for release types and schedule, and the xref:releasing_guide/releasing_guide.adoc[Releasing Guide] for the oCIS release process. == Changelog Entries -For a user-facing Web change, add a changelog entry to the oCIS root `changelog/unreleased/` folder, based on `changelog/TEMPLATE`: +For a user-facing Web change, add a changelog entry to the oCIS root `changelog/unreleased/` folder, based on `changelog/TEMPLATE`. These entries are what the oCIS release workflow (`.github/workflows/release.yml`) turns into the release notes of the GitHub release, using calens: * The first line starts with the change type `Bugfix`, `Change` (breaking change), `Enhancement` (new feature) or `Security`, followed by a short title. * The body describes the change, wrapped at 80 characters. @@ -19,7 +19,7 @@ For a user-facing Web change, add a changelog entry to the oCIS root `changelog/ Existing Web entries are named like `bugfix-web-embed-delegated-token-renewal.md` or `enhancement-web-bump-pinia.md`. Do not create or move versioned changelog folders, this is part of the oCIS release process. -In addition, PR titles follow link:https://www.conventionalcommits.org[Conventional Commits] as described in `COMMIT_CONVENTION.md`. Web changes usually use `web` as the scope, for example `fix(web): [OCISDEV-1572] show an error when a copy gets no answer`. PRs are squash-merged and release notes are generated from these titles with git-cliff. +In addition, PR titles must follow link:https://www.conventionalcommits.org[Conventional Commits] as described in `COMMIT_CONVENTION.md`; the `pr-title.yml` workflow checks this. Web changes usually use `web` as the scope, for example `fix(web): [OCISDEV-1572] show an error when a copy gets no answer`. PRs are squash-merged, so the title becomes the commit message. `make changelog-generate` can build notes from these titles with git-cliff, but no release workflow uses that yet, so the changelog entry is still required. == Translations