You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-17Lines changed: 1 addition & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# @apostrophecms/content-upgrader
2
2
3
-
A tool to migrate your **content** from Apostrophe 2.x to Apostrophe 4.x. That is, it creates a new database in the A3/A4 format, and copies over the uploaded media. This tool does not upgrade your source code, however a Claude Skill is provided for that (see "migrating your code," below below).
3
+
A tool to migrate your **content** from Apostrophe 2.x to Apostrophe 4.x. That is, it creates a new database in the A3/A4 format, and copies over the uploaded media. This tool does not upgrade your source code, see our `code-upgrader` module for that.
4
4
5
5
See also [Coming from Apostrophe 2.x](https://apostrophecms.com/docs/guide/migration/upgrading.html), especially the Breaking Changes section.
6
6
@@ -10,22 +10,6 @@ See also [Coming from Apostrophe 2.x](https://apostrophecms.com/docs/guide/migra
10
10
* A2 has a built-in `apostrophe-images` "slideshow" widget type, while A4 only has a built-in single-image `@apostrophecms/image` widget type. By default `apostrophe-images` will be upgraded to `@apostrophecms/image`, with only the first image present in each. However you can use the `mapWidgetTypes` option, documented below, to override this mapping during the upgrade.
11
11
* A4 does not have a standard "piece widget" with support for display of all widgets, handpicked widgets, or tagged widgets in the same way that A2 does. Instead, these are well-documented examples of custom widgets. You will need to use `mapWidgetTypes` accordingly after developing an appropriate solution for your needs in your A4 project.
12
12
13
-
## Migrating your code
14
-
15
-
In order to make practical use of this module, you'll need a matching A4 project with essentially the same features. To migrate your existing code, we recommend making a fresh checkout of your project with a branch name like `a4`. Also change `shortName`, adding `-a4` so that the database name will be distinct from your A2 project. Then choose one of the two paths below:
16
-
17
-
### AI code migration tips
18
-
19
-
Take advantage of the [Agent skill, aka Claude skill, we provide for this purpose](https://github.com/apostrophecms/content-upgrader/blob/main/skills/migrate-a2-to-a4/). For use with Claude Code, copy the `skills/migrate-a2-to-a4` folder of this repository to `.claude/skills/migrate-a2-to-a4` within your home directory, or your project. Then ask Claude Code to migrate the project to Apostrophe 4.x using the skill. Active developer involvement and testing is required, but you will save a tremendous amount of time by following this approach.
20
-
21
-
Agent skills are also supported by other AI coding tools. Install the skill according to your preferred agent's instructions. Then make sure the agent is actually using the skill (it will tell you).
22
-
23
-
**A good understanding of A4 and the migration process is still required.** Although Claude Code has done **most** of the work for two migrations for us so far, you will definitely need to prompt various corrections and changes. We strongly recommend reading all of the "manual code migration tips" below.
24
-
25
-
### Manual code migration tips
26
-
27
-
Of course manual upgrades are also supported. See [Coming from Apostrophe 2.x](https://apostrophecms.com/docs/guide/migration/upgrading.html) as well as the [recommendations in the agent skill,](https://github.com/apostrophecms/content-upgrader/blob/main/skills/migrate-a2-to-a4/SKILL.md) which are big time-savers for manual development as well.
28
-
29
13
## Installation
30
14
31
15
This tool installs as a module **inside your existing A2 project.** This is necessary to gain access to information such as the schemas of your existing piece and page and widget types.
0 commit comments