Realtime sync for any backend stack
npm install @rocicorp/replicacheFirst look for API changes. Download the last release and compare the .d.ts files:
``bashBUILD
cd rocicorp/mono
npm run build
We need to be very careful about public API changes as we then have to maintain them. Make sure all new API has been discussed and agreed to by the team.
Next look through all changes in the repo since the last release. To do this properly:
`bash
List all commits on main from the commit prior to last tag (which should be
present on main) to HEAD.
git log replicache/v$LAST_RELEASE_VERSION^..HEAD
`Build a list of all changes that affect Replicache. This will become the release notes later.
- If there are any breaking changes, then this needs to be a new major version.
- If there are any new (non-breaking) features, then this needs to be a new minor version.
- Otherwise, if there are only non-breaking bugfixes, it's a patch.
Get a clean checkout
`bash
rm -rf /tmp/release
mkdir /tmp/release
cd /tmp/release
git clone --depth=1 git@github.com:rocicorp/mono.git
cd mono
npm install
`Bump the version
`bash
vim packages/replicache/package.json
Must be done in root of mono checkout
npm install
npx syncpack fix-mismatches
npm install
git commit -a -m 'chore(replicache): Bump version to v$NEW_VERSION'
`Publish a canary
`bash
cd packages/replicache
npm publish --tag=canary
`Tag the Release
We tag the release _on the branch_. This is important because we only want to
tag the code we just tested above, not any other code that may have landed on
main in the meantime.
`bash
From temp dir we published from above
git tag replicache/v$NEW_VERSION
git push origin --tags
`Merge the Release
`bash
From your main checkout (not temp dir)
git fetch -t
git merge replicache/v$NEW_VERSION
git push origin main
`Manual Testing
$3
Test that the
get-license script still works:`bash
npx replicache@canary get-license
`Go through the flow and ensure you get a license.
$3
Check out each of the todo samples. Install the canary version:
`bash
npm add replicache@canary
`Then run the app and ensure it works properly.
Push a PR (but don't land yet) that update to new version.
$3
Check out rocicorp/repliear
Same as todo.
$3
Go through https://doc.replicache.dev/tutorial and test still works / make any updates necessary
$3
Walk through the integration guide and make sure things still work.
Update the peer libraries for compat with the new Replicache
If the major version changed, then update the following packages that have peerDependencies on Replicache:
-
replicache-nextjs
- rails
- replicache-transactionFinish Release Notes
We write the release notes in
Notion
and publish them to the web.
Finalize the release notes based on the list of relevant changes you gathered
earlier.
$3
Also copy the release notes to Discord. If the release notes are long summarize it.
Push and test all the sample apps
Switch the Release to Latest
We already have the npm package on npmjs.com but it is tagged as
@canary. We
want @latest to point at the same release. To do this, we use npm dist-tag:`bash
note: this will publish the release to the "latest" tag, which means it's what
people will get when they
npm install. If this is a beta release, you should
use the
beta tag but also make sure the semver has beta in it.
npm dist-tag add replicache@$NEW_VERSION latest
`Publish the Private Release
We also publish a private release with the name
@rocicorp/replicache to
npmjs.org which does not
minimize the code and includes the sourcemaps. This npm package may be used by
paying customers to make it easier to debug their code.`bash
git checkout rocicorp-replicacheMerge new release
git merge replicache/v$NEW_VERSIONVerify that the only diff is the name and the sourcemap
git diff replicache/v$NEW_VERSIONgit push origin rocicorp-replicache
npm publish
`Release docs
The docs are built from the
docs branch so we need to rebase that to get it
to deploy a new version.`
git checkout docs
git pull
git reset --hard replicache/v$NEW_VERSION
git push origin docs
`Important: Only do this when releasing a new version, otherwise we will release early docs that don't match current released code. To cherry-pick doc improvements see: "sprucing the docs", below.
Note: It's likely that when you
git push origin docs above, you'll get a conflict error. This is expected if there have been any cherry-picks onto this branch as would happen if somebody "spruced" (below). Check that all the new commits on this docs branch since the last release are present in origin/main. To do this, for each such commit, there should be a message Cherry-picked from in the commit message. This message is added by the "spruce" procedure. Look for each such in origin/main. If all such commits on docs are present in origin/main then you can force the push with git push origin docs --force. If there is a commit on this branch which is missing from origin/main then somebody edited directly on this branch and it should be investigated.TODO: We should write a script
release-docs.sh to automate the above.---
Sprucing the docs
The live docs at doc.replicache.dev are served from the
docs channel so that they reflect the stable API.However, this means that if you do cleanup docs changes that you want to show up immediately, you need to cherry-pick the changes onto the
docs branch:`
git checkout docs
git pull
The '-x' appends the hash of the original commit to the cherry-pick'd commit.
This makes it easier to find missing commits during releases.
git cherry-pick -x
git push origin docs
`During release, below, we reset the
docs branch to main, dropping these cherry-picked changes. So it's important to never do work directly on docs.Performance Monitoring
We continuously track performance across a variety of benchmarks and the size of Replicache's bundle.
Results here:
- Performance Benchmarks
- Bundle Sizes
The runner runs on an ec2 instance you can find here or through the ec2 aws console. If you need
to set it up again you can kill the existing runner processes, rm the old
actions-runner directory, and
then follow the github instructions for installing a runner. You will want to use runsvc.sh install and runsvc.sh start instead of run.sh so it
keeps running after you detach.Local Debugging with Source Maps
To debug and develop Replicache locally in a webpack-based app, you need to tweak a few things.
If you haven't already done so, make
replicache-internal available to npm by using npm-link, and create a debug build.`bash
in your replicache-internal dir
npm linkcreates an unminified and unmangled build so that you can see symbols in the debugger/watches
npm run build -- --debug
`In your app you want to debug, link the replicache package, and install the
source-map-loader package:`bash
cd
npm link replicachenpm install -D source-map-loader
`Modify the webpack config to include third-party source maps in its bundle.
For our sample apps (Next.js based), modify the next config:
`js
// next.config.js
module.exports = {
...
webpack: (config) => {
config.module.rules.push({
test: /\.mjs$/,
use: ["source-map-loader"],
});
return config;
},
...
}``