Skip to content

Commit

Permalink
Support Controlled Documents import
Browse files Browse the repository at this point in the history
Signed-off-by: Anna Khismatullina <[email protected]>
  • Loading branch information
akhismat committed Dec 24, 2024
1 parent 949e7c2 commit 3e496c6
Show file tree
Hide file tree
Showing 13 changed files with 1,450 additions and 204 deletions.
40 changes: 20 additions & 20 deletions common/config/rush/pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

148 changes: 116 additions & 32 deletions dev/import-tool/docs/huly/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,24 @@ workspace/
│ └── files/
│ └── diagram.png # Can be referenced in markdown content
└── Project Alpha.yaml # Project configuration
├── QMS Documents/ # QMS documentation
│ ├── [SOP-001] Document Control.md # Document template
│ ├── [SOP-001] Document Control/ # Template implementations
│ │ └── [SOP-002] Document Review.md # Controlled document
│ └── [WI-001] Document Template Usage.md # Standalone controlled document
└── QMS Documents.yaml # QMS space configuration
```

### File Format Requirements
* All spaces files must be in YAML format
* All document/issue files must include YAML frontmatter followed by Markdown content
* Children documents/issues are located in the folder with the same name as the parent document/issue

#### Space Configuration (*.yaml)
Project space (`Project Alpha.yaml`):

#### Tracker Issues

##### 1. Project Configuration (*.yaml)
Example: `Project Alpha.yaml`:
```yaml
class: tracker:class:Project # Required
title: Project Alpha # Required
Expand All @@ -51,32 +63,8 @@ description: string # Optional
defaultIssueStatus: Todo # Optional
```
Teamspace (`Documentation.yaml`):
```yaml
class: document:class:Teamspace # Required
title: Documentation # Required
private: false # Optional, default: false
autoJoin: true # Optional, default: true
owners: # Optional, list of email addresses
- [email protected]
members: # Optional, list of email addresses
- [email protected]
description: string # Optional
```

#### Documents and Issues (*.md)
All files must include YAML frontmatter followed by Markdown content:

Document (`Getting Started.md`):
```yaml
---
class: document:class:Document # Required
title: Getting Started Guide # Required
---
# Content in Markdown format
```

Issue (`1.Project Setup.md`):
##### 2. Issue (*.md)
Example: `1.Project Setup.md`:
```yaml
---
class: tracker:class:Issue # Required
Expand All @@ -90,11 +78,11 @@ remainingTime: 4 # Optional, in hours
Task description in Markdown...
```

### Task Identification
* Human-readable task ID is formed by combining project's identifier and task number from filename
* Example: For project with identifier "ALPHA" and task "1.Setup Project.md", the task ID will be "ALPHA-1"
##### Issue Identification
* Human-readable issue ID is formed by combining project's identifier and issue number from filename
* Example: For project with identifier `ALPHA` and issue `1.Setup Project.md`, the issue ID will be `ALPHA-1`

### Allowed Values
##### Allowed Values

Issue status values:
* `Backlog`
Expand All @@ -109,6 +97,99 @@ Issue priority values:
* `High`
* `Urgent`

#### Documents

##### 1. Teamspace Configuration (*.yaml)
Example: `Documentation.yaml`:
```yaml
class: document:class:Teamspace # Required
title: Documentation # Required
private: false # Optional, default: false
autoJoin: true # Optional, default: true
owners: # Optional, list of email addresses
- [email protected]
members: # Optional, list of email addresses
- [email protected]
description: string # Optional
```

##### 2. Document (*.md)
Example: `Getting Started.md`:
```yaml
---
class: document:class:Document # Required
title: Getting Started Guide # Required
---
# Content in Markdown format
```

#### Controlled Documents
##### 1. Space Configuration (*.yaml)
QMS Document Space: `QMS Documents.yaml`:
```yaml
class: documents:class:OrgSpace # Required
title: QMS Documents # Required
private: false # Optional, default: false
owners: # Optional, list of email addresses
- [email protected]
members: # Optional, list of email addresses
- [email protected]
description: string # Optional
qualified: [email protected] # Optional, qualified user
manager: [email protected] # Optional, QMS manager
qara: [email protected] # Optional, QA/RA specialist
```

##### 2. Document Template (*.md)
Example: `[SOP-001] Document Control.md`:
```yaml
---
class: documents:mixin:DocumentTemplate # Required
title: SOP Template # Required
docPrefix: SOP # Required, document code prefix
category: documents:category:Procedures # Required
author: John Smith # Required
owner: Jane Wilson # Required
abstract: Template description # Optional
reviewers: # Optional
- [email protected]
approvers: # Optional
- [email protected]
coAuthors: # Optional
- [email protected]
---
Template content in Markdown...
```

##### 3. Controlled Document (*.md)
Example: `[SOP-002] Document Review.md`:
```yaml
---
class: documents:class:ControlledDocument # Required
title: Document Review Procedure # Required
template: [SOP-001] Document Control.md # Required, path to template
author: John Smith # Required
owner: Jane Wilson # Required
abstract: Document description # Optional
reviewers: # Optional
- [email protected]
approvers: # Optional
- [email protected]
coAuthors: # Optional
- [email protected]
changeControl: # Optional
description: Initial document creation
reason: Need for standardized process
impact: Improved document control
---
Document content in Markdown...
```
##### Controlled Document Code Format
* Document code must be specified in file name: `[CODE] Any File Name.md`
* If code is not specified for controlled document, it will be generated automatically using template's docPrefix and sequential number (e.g. `SOP-99`)
* If code is not specified for template, it will be generated automatically as `TMPL-seqNumber`, where `seqNumber` is the sequence number of the template in the space


### Run Import Tool
```bash
docker run \
Expand All @@ -125,3 +206,6 @@ docker run \
* All users must exist in the system before import
* Assignees are mapped by full name
* Files in space directories can be used as attachments when referenced in markdown content
* Document codes (in square brackets) must be unique across all document spaces
* Controlled documents must be created in the same space as their templates
* Controlled documents can be imported only with `Draft` status
11 changes: 11 additions & 0 deletions dev/import-tool/docs/huly/example-workspace/QMS Documents.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
class: documents:class:OrgSpace
title: QMS Documents
description: Quality Management System Documentation
private: false
owners:
- [email protected]
members:
- [email protected]
qualified: [email protected]
manager: [email protected]
qara: [email protected]
Loading

0 comments on commit 3e496c6

Please sign in to comment.