Skip to content

Commit

Permalink
migration page added
Browse files Browse the repository at this point in the history 
Signed-off-by: henkvancann <[email protected]>
  • Loading branch information
@henkvancann
henkvancann committed Nov 12, 2024
1 parent 2be285b commit f7121b9
Showing 1 changed file with 106 additions and 73 deletions.
179 changes: 106 additions & 73 deletions docs/general/migration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ sidebar_position: 1

**Pre condition: You have a Spec-Up installation up and running**


## What you'll need

- A terminal / Command Line
Expand All @@ -17,120 +16,154 @@ sidebar_position: 1
- A [webbrowser](https://en.wikipedia.org/wiki/Web_browser). You are probably reading this in a browser, so you already have one
- [Git](https://git-scm.com/). To host your specification on Github, you must also have Git installed on your local system. By the way, you can also create a specification (index.html) without hosting it on GitHub. But if you do so, the whole idea of a version-managed glossary using Git goes through the window.

:::info
::: note Non-technical Info
Non-technical explanation:
- Command Line: A text interface to type commands for your computer.
- IDE: A software where you can easily write, test, and debug code.
- Node.js: This makes Spec-Up and Spec-Up-T run
- Git: A system to track and manage changes in your code.
:::

## Organize your Terminology data
## Save your data

Back-up Specs.json to specs-backup.json

Back-up package.json to package-backup.json

- Split your Terms and Definition into seperate files under a directory in `/spec` directory
- Adjust your Spec.json accordingly
- Add a Terms-spec.json
-
```
mv specs.json specs-backup.json
mv package.json package-backup.json
```

Be sure to get the latest specs.json [here](https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-starterpack/specs.json) from the starter pack and save into the root of the repo.

## Modify your Spec-Up installation with Spec-Up-T install

### General info
We consider migration a task for the roles `developer` or `administrator`.

Installing Spec-Up-T is as follows:
It's about file management. It's in line with how static website generator generally work. So, be aware that you only organize your files in the migration process, you then configure your configuration files and you're good to go. Spec-Up-T will:

- Install the tool via `npx`
- Install the spec-up-t package via `npm`
- create the `terms-index.json` in the root of the repo
- generate the glossary in `index.html`
- creates `specs-generated.json` in the output directory, DON'T TOUCH
- creates `terms-and-definitions-intro.md` in the `/spec` directory DON'T TOUCH

It is explained in more detail below:
### Feel free to reorganize the order of term in the glossary
Open the `terms-index.json` with a text editor in the root of the repo and change the order of terms. You can even throw terms out.

### Let's create
::: note Plan to change
`terms-index.json` will be a file that can't be editted by the user. We'll create the following process:
- a user bypasses a term file (that is in draft) using an `_` (underscore) as the first character of the file name
- a user create a custom order (default: alphabetically) by putting an order number as the first 3 characters of a filename. Example: `10_validator.md`, `15_autonomous-identifier.md`, etc.

This method is adopted from Docusaurus.
:::

```bash
npx create-spec-up-t my-spec-up-t-website
```
### Prepare specs.json

*my-spec-up-t-website* can be anything you want it to be (however, it is recommended to not use spaces or special characters in directory names).

You can also omit the last part:
#### We copy the new specs.json structure for Spec-Up-T

```bash
npx create-spec-up-t
```json
{
"specs": [
{
"title": "Spec-Up-T Starterpack",
"spec_directory": "./spec",
"spec_terms_directory": "terms-definitions", | <- choose your name! |
"output_path": "./docs",
"markdown_paths": [
"intro.md",
**| copy your .md files here, listed in specs.json-backup, excluding the terminology md files |**
],
"logo": "https://raw.githubusercontent.com/blockchainbird/spec-up-t-starter-pack/main/spec-up-t-starterpack/logo.svg",
"logo_link": "https://github.com/blockchainbird/spec-up-t",
"source": {
"host": "github",
"account": "blockchainbird",
"repo": "spec-up-t-demo-on-documentation-website"
},
"external_specs": [
{
"test-1": "https://blockchainbird.github.io/spec-up-xref-test-1/"
},
{
"test-2": "https://blockchainbird.github.io/spec-up-xref-test-2/"
}
],
"external_specs_repos": [
{
"external_spec": "test-1",
"url": "https://github.com/blockchainbird/spec-up-xref-test-1",
"terms_dir": "spec/term-definitions"
},
{
"external_spec": "test-2",
"url": "https://github.com/blockchainbird/spec-up-xref-test-2",
"terms_dir": "spec/term-definitions"
}
],
"katex": false,
"searchHighlightStyle": "ssi"
}
]
}
```

If you omit `my-spec-up-t-website`, a default directory name, namely `spec-up-t-starterpack,` is used.
Be sure to get the latest specs.json [here](https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-starterpack/specs.json)

Sometimes, you want to force the latest version to be installed. Then you can do the following:
Copy your old order of files from `specs-backup.json` and add `terms-and-definitions-intro.md` somewhere in the list (you choose the order!)

```bash
npx create-spec-up-t@latest my-spec-up-t-website
```
#### Alter package.json
Follow the instructions here: [Update package.json](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#packagejson)

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. It should work on any operating system (not tested yet).
#### Copy Spec-Up-T specific files
Follow the instructions here: [Make Spec-Up-T operational](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#copy-files-to-the-root-of-your-installation)

You should now have a directory called `my-spec-up-t-website` (or `spec-up-t-starterpack` if you did not specify a name).
#### Terms in their own directory
| TBW why are we doing this |
You should place the terms in their own directory. This directory is defined in specs.json as `spec_terms_directory`.

### Go into the directory
Alter the configuration according to your wishes and place all term-files the directory. Also see [Organize your Terminology data](#organize-your-terminology-data)

- Go into this directory (folder) that was just created:
#### Npm Install
Delete your `node_modules` directory and `package-lock.json` file.

```bash
cd my-spec-up-t-website
Install Spec-Up-T and install all dependencies:
```
npm install
```
Go into the menu

You are now in this directory.
```
npm run menu
```

### Install all dependencies
Add new terms: option 6

- Install all dependencies:
Generate the specification

```bash
npm run install
```
npm run menu
1
```

It can take some time, and you should see multiple lines of output during installation.

When the prompt is visible again, you should now have a basic Spec-Up-T install:
When the prompt is visible again, you should now have a Spec-Up-T install of your former Spec-Up install:

- a `specs.json` file
- a `spec/` directory with sample markdown files
- a `node_modules` directory, a `package.json` file, and a `package-lock.json` file (these three elements belong to the `npm` system)
- a `specs.json` file of the Spec-Up-T structure
- a `spec/` directory with your markdown files
- a `node_modules` directory, and a `package-lock.json` file (these elements belong to the `npm` system together with the earlier processed, modified-by-hand `package.json`)

What you don't have yet is the following:
What you also should have is:

- a `docs` directory with a sample `index.html` file (which is the actual specification file that is the goal of it all).

How to do this, go to the [General Instructions](./command-line-menu.md).
- a `docs` directory with a generated `index.html` file (which is the actual specification file that is the goal of it all).

### Add repo to Github

You should push your new specification (i.e. the sample content) to a GitHub repo.

These are the steps to take:

#### Edit `specs.json`

Change this entry in `specs.json`:

```json
"source": {
"host": "github",
"account": "blockchainbird",
"repo": "spec-up-t-starter-pack"
}
```
Follow the steps to take here if you want to use a different account or repo: [Add repo to Github](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#copy-files-to-the-root-of-your-installation)

to the correct information:

```json
"source": {
"host": "github",
"account": "your-account",
"repo": "your-repo"
}
```

These are the host (GitHub), your GitHub account name, and the repo name of the repo you are about to push.

#### Commit and Push repo to GitHub
## Organize your Terminology data
- Split your Terms and Definition into separate files under a directory in `/spec` directory

Now, commit your changes and push the repo to GitHub. Use the command line or your preferred way to do this.

0 comments on commit f7121b9

Please sign in to comment.