@cooperco/cooper-component-library 0.1.62 → 0.1.64

package/dist/cms/README.md

@@ -1,112 +1,42 @@
-# GraphQL Queries
+# Migrations
 
-This directory contains GraphQL queries for fetching content from Contentful CMS.
+## Prerequisites
 
-## Directory Structure
+- Run `pnpm install`
+- Obtain a Contentful CMA token
+- Confirm and double check what space and environment you should be running these in
+- Run `pnpm exec contentful-cli-migrations --environment-id <your-env-name> --space-id <space-id> --management-token <CMA-TOKEN> --initialise` on environment if not already and update `.env`
 
-```
-cms/contentful/queries/
-├── index.ts                    # Barrel export file (manual updates required)
-├── fragments.ts                # Shared GraphQL fragments
-├── *.query.ts                  # Individual component queries
-└── README.md                   # This file
-```
 
-## How Queries Are Exported
+## Helpful Docs
 
-The query export system in this project is **semi-automatic**:
+- [Contentful Migration](https://github.com/contentful/contentful-migration)
+- [Contentful Migration Reference Docs](https://github.com/contentful/contentful-migration/blob/main/README.md#reference-documentation)
+- [Contentful Data Model](https://www.contentful.com/developers/docs/concepts/data-model/)
 
-### The Process
+### Instructions
 
-1. **Individual Query Files** - Queries are defined in individual files with the pattern `*.query.ts`
-   - Example: `accordion.query.ts`, `carousel.query.ts`
+- Create your migration file in the scripts folder with the following format: `0002-description.cjs`
+- Write your migrations
+  - This should be with an up and a down function
+  - The up function updates the model
+  - The down function reversts your changes
+- Run your migration on a test environment with the following command: `pnpm exec contentful-cli-migrations --environment-id <your-env-name> --space-id <space-id> --management-token <CMA-TOKEN>`
+  - Optional Flags:
+    - `--rollback`: Rolls back one migration.
 
-2. **Manual Barrel Export** - Queries are re-exported through `index.ts`
-   - Uses wildcard exports: `export * from './accordion.query.js'`
-   - **Note:** Exports use `.js` extensions even though source files are `.ts` (ESM compatibility)
+### Gotchas
 
-3. **Package-Level Export** - The barrel export is exposed via `package.json`:
-   ```json
-   "./cms/contentful/graphql": {
-     "import": "./dist/cms/contentful/queries/index.js",
-     "types": "./dist/cms/contentful/queries/index.d.ts"
-   }
-   ```
+- Currently the rollback may change the version counter even if the migration doesnt run.
+  - for this just update the counter to the correct counter in contentful and rerun.
+- The migration may run and create a content type even if the whole migration doesnt run correctly.
+  - To fix you will need to delete the content type and re-run
 
-## Creating a New Query
+### TODO
 
-### Steps Required
-
-1. **Create Query File** - Add your query file: `yourComponent.query.ts`
-
-2. **Define Query** - Follow the established pattern:
-   ```typescript
-   import { gql } from 'graphql-tag'
-   import type { DocumentNode } from 'graphql'
-   import { someFragment } from './fragments.js' // If needed
-
-   export const getYourComponent: DocumentNode = gql`
-     ${someFragment}  // Include fragments if needed
-     query yourComponentQuery($id: String!, $preview: Boolean = false) {
-       yourComponent(id: $id, preview: $preview) {
-         __typename
-         # Add your fields here
-       }
-     }
-   `
-   ```
-
-3. **Update Barrel Export** - **MANUALLY ADD** export to `index.ts`:
-   ```typescript
-   export * from './yourComponent.query.js'
-   ```
-   - Maintain alphabetical order for consistency
-   - Use `.js` extension (not `.ts`)
-
-### Query Naming Conventions
-
-- **File Name:** `componentName.query.ts` (camelCase)
-- **Export Name:** `getComponentName` (camelCase with `get` prefix)
-- **Query Name:** `componentNameQuery` (camelCase with `Query` suffix)
-
-### Example
-
-```typescript
-// accordion.query.ts
-import { gql } from 'graphql-tag'
-import type { DocumentNode } from 'graphql'
-import { accordionItemFragment } from './fragments.js'
-
-export const getAccordion: DocumentNode = gql`
-  ${accordionItemFragment}
-  query accordionQuery($id: String!, $preview: Boolean = false) {
-    accordion(id: $id, preview: $preview) {
-      __typename
-      headline
-      accordionType
-      loadMoreButtonTitle
-      startOpen
-      accordionItemCollection {
-        items {
-          ...accordionItemFragment
-        }
-      }
-    }
-  }
-`
-```
-
-## Using Queries in Consumer Projects
-
-Queries are consumed via the package export:
-
-```typescript
-import { getAccordion, getCarousel } from '@cooperco/cooper-component-library/cms/contentful/graphql'
-```
-
-## Important Notes
-
-- **Manual Export Required:** The system is NOT fully automatic - you MUST manually update `index.ts` when adding new queries
-- **ESM Extensions:** Always use `.js` extensions in exports (even for `.ts` source files)
-- **Preview Mode:** All queries support a `preview` parameter for Contentful preview API
-- **Fragments:** Shared fragments are defined in `fragments.ts` and can be reused across queries
+- Fix rollback versioning
+  - This flag should cause a rollback to that specific version, in this case 0001 `--version 0001`
+  - It should be used with `--rollback`
+  - It should update dthe versionTracker entry on successful rollback
+- Run migration error handling
+  - runMigration is currently not working as expected and bumping the counter when the migration was aborted