How Tos - serlo/documentation GitHub Wiki

How to update dependencies?

Variant 1: Do it manually

yarn dependencies

Use yarn upgrade-interactively and update the dependency or a list of dependencies. Run all checks (e.g. via yarn check:all) and fix errors which occur. In case of updates in the major version have a look at the changelog of the dependency where breaking changes are defined. Don't forget to run yarn dedupe after your updates (deduplicates dependencies with overlapping ranges, see https://yarnpkg.com/cli/dedupe).

It is recommended to make smaller commits / PRs with only some updates instead of always updating everything. Merge the PRs into main when some updates succeed and do not break the CI.

cargo dependencies

To edit your versions in Cargo.toml, you can use

$ cargo upgrade

if you want also for a specific dependency only.

If you only want to update your lock file without editing your Cargo.toml for newer versions, do

$ cargo update

Variant 2: Set up and use dependa-bot

See https://docs.github.com/en/code-security/dependabot/working-with-dependabot, set it up in the repository and merge the PRs. In case the CI breaks, fix the error in the particular pull request.

How to update the version of Node.JS / Rust / Python

We manage asdf for our tool chain. Here you can also update the used programming language. Example with Node.JS:

# List all versions of Node.JS
asdf list all nodejs

# Install version X
asdf install nodejs X

In case the repository has a .tool-versions file make sure that you change it accordingly (e.g. via asdf local nodejs X). After installing the new version make sure that you make the appropriate changes in the repository:

• Update GitHub actions (for example https://github.com/serlo/cloudflare-worker/blob/47fc44af9841fb67c5c42696aa30fd74e0865c7a/.github/workflows/js.yml#L11 need to have the right version)
• Update Dockerfile for all created docker files (example https://github.com/serlo/api.serlo.org/blob/56aff08b8c5d3d66602c53190d47ac1544d76b2b/packages/server/docker/server/Dockerfile#L1)
• For Node.JS: Update engines in package.json (see https://github.com/serlo/cloudflare-worker/blob/47fc44af9841fb67c5c42696aa30fd74e0865c7a/package.json#L83-L85)
• Make sure everything is still working (tests, lints, build of docker images, ...)

How to update yarn?

See https://yarnpkg.com/cli/set/version

How release a new version of api.serlo.org

The first part consists of bumping the version of api.serlo.org. The bumping of a new version of serlo/api.serlo.org and its packages:

• @serlo/authorization
• @types/graphql-modules
• @serlo/api.serlo.org
• @serlo/api

is done via the scripts/update_version.sh script.

To create the new version and release it:

1. Checkout the serlo/api.serlo.org repository and create a new branch that will be used for the changes that will be generated to create the new tag version.
2. Make sure that the core.editor git config is set in the host where you are running the script.
3. Run yarn update-version.
4. You will see that the scripts/changelog.ts file will open in the editor you setup in step 2.
5. In the release property of the scripts/changelog.ts file, add a new object with the tagName, date and the changes that are included in the new release (here you can see the shape of the release Section).
   • To get information on the included changes, you can compare the latest tag (e.g. https://github.com/serlo/api.serlo.org/releases/tag/v0.52.0) with the main branch (e.g. https://github.com/serlo/api.serlo.org/compare/main..v0.52.0) and review the changes that were made between the two versions).
6. Save the changes in the scripts/changelog.ts file.
7. Then, you will see the following message: "Generating CHANGELOG" in the console output and that the package.json files and the yarn.lock file will be updated by the scripts/update_version.sh script.
8. Then git commit will be executed for the changes that were updated in the step 7 to be committed. In this step you may stage the changes, and write a message such as: "Release version MAJOR.MINOR.PATCH"
9. Push the changes to the remote branch that was created in step 1. and open a PR.
10. Verify that all the GitHub Actions checks pass, ask for a review of your changes, and then, merge the PR with the new version changes.
    • On the merge to the main branch, the Deploy workflow will run, and it will build the new api-server and api-swr-queue-worker images and tag them with the version that was created in the previous steps. The images will also be pushed to the Google Cloud Container Registry.

How release a new version of database-layer

The first part consists of bumping the version of the server in the database-layer repository. This is done via the scripts/update_server_version.sh script.

To create the new version and release it:

1. Clone the database-layer repository and create a new branch that will be used for the changes that will be generated to create the new tag version.
2. Make sure that the core.editor git config is set in the host where you are running the script.
3. Run the script ./scripts/update_server_version.sh.
4. You will see that the scripts/changelog.ts file will open in the editor you setup in step 2.
5. In the release property of the scripts/changelog.ts file, add the new object with a tagName, date and the changes that are included in the new release (here you can find the shape of the release Section).
   • To get information on the included changes, you can compare the latest tag (e.g. https://github.com/serlo/database-layer/releases/tag/v0.3.66) with the main branch (e.g. https://github.com/serlo/database-layer/compare/main..v0.3.66) and review the changes that were made between the two versions).
6. Save the changes in the scripts/changelog.ts file.
7. Then, you will see the following message: "Generating CHANGELOG" in the console output and that the package.json files and the yarn.lock file will be updated by the scripts/update_server_version.sh script.
8. Then git commit will be executed for the changes that were updated in the step 7 to be committed. In this step you may stage the changes, and write a message such as: "Release version MAJOR.MINOR.PATCH"
9. Push the changes to the remote branch that was created in step 1. and open a PR.
10. Verify that all the GitHub Actions checks pass, ask for a review of your changes, and then, merge the PR with the new version changes.
    • On the merge to the main branch, the Deploy workflow will run, and it will build the new serlo-org-database-layer image and tag it with the version that was created in the previous steps. The image will also be pushed to the Google Cloud Container Registry.

How to manually run db-setup in staging

Go to https://console.cloud.google.com/ and make sure, that you have selected serlo-staging as a project:

Go to "menu > Kubernetes Engine > Workloads" and select dbsetup. The site should look like this:

Select "Run now". Wait until in "managed Pods" at the bottom of the page the status becomes "Succeeded". Note that this means, that the DB migration is still running:

How to rerun db-migrations manually

Prerequisites: If necessary: Run db-setup again (see above) – this step is necessary when you have made changes to the DB migration (for example by fixing a bug) and you want to run it again.

Go to https://console.cloud.google.com/ and make sure, that you have selected serlo-staging as a project:

Go to "menu > Kubernetes Engine > Workloads" and select db-migration-cronjob. Click "Run now" (after db-setup succeeded).