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..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 +| 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/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..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 @@ -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. 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. -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`. These entries are what the oCIS release workflow (`.github/workflows/release.yml`) turns into the release notes of the GitHub release, using calens: -=== 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 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. -. 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].