Improve architecture and design principles documentation

kamiazya · kamiazya · commit bd669ed2e9f7 · 2024-11-22T09:51:28.000+09:00
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/00-overview.md b/docs/ts-graphviz/12-architecture-and-design-principles/00-overview.md
@@ -0,0 +1,5 @@
+# Overview
+
+Understanding the architecture and design principles of ts-graphviz helps you utilize the library more effectively and contribute to its development.
+
+This section provides insights into the foundational concepts, architectural decisions, and guiding principles that shape ts-graphviz.
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/01-design-principles.md b/docs/ts-graphviz/12-architecture-and-design-principles/01-design-principles.md
@@ -0,0 +1,31 @@
+# Design Principles
+
+**ts-graphviz** is built around several key concepts that make it modular, extensible, and easy to use:
+
+1. **TypeScript-First Design & Type Definitions**
+
+    **ts-graphviz** is designed primarily with TypeScript in mind, offering strong typing and seamless integration with TypeScript projects. Comprehensive type definitions for DOT language elements enable type-safe interactions, enhancing development efficiency and reducing errors.
+
+1. **Object-Oriented API**
+
+    The library provides an object-oriented API for creating and manipulating graph elements such as graphs, nodes, and edges. This approach makes working with complex graph structures intuitive and efficient, leveraging familiar programming paradigms.
+
+1. **Modular Design**
+
+    **ts-graphviz** adopts a modular architecture, split into multiple packages, each serving a specific purpose. This modularity allows users to include only the functionality they need, improving maintainability, flexibility, and reducing unnecessary dependencies.
+
+1. **AST Support**
+
+    The library includes support for Abstract Syntax Trees (AST) for processing the DOT language. This enables parsing and generating DOT language while preserving its structure, facilitating programmatic manipulation and transformation of graphs.
+
+1. **Runtime Adapter**
+
+    To ensure compatibility across different runtime environments, **ts-graphviz** provides adapter functions for environments like Node.js and Deno. These adapters serve as a wrapper, enabling seamless execution of Graphviz commands regardless of the underlying platform.
+
+1. **Extensibility**
+
+    Designed with extensibility in mind, **ts-graphviz** allows users to extend its functionality with custom implementations for specific use cases. This flexibility supports a wide range of applications and integration scenarios.
+
+1. **Multi-Paradigm Support**
+
+    The library accommodates various programming paradigms, including Object-Oriented Programming, Declarative Programming, and Functional Programming. Users can choose the style that best suits their needs, making the library versatile and adaptable.
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/02-package-architecture.md b/docs/ts-graphviz/12-architecture-and-design-principles/02-package-architecture.md
@@ -0,0 +1,29 @@
+# Package Architecture
+
+**ts-graphviz** consists of several packages, each with a specific role:
+
+- **`ts-graphviz`** (Main Package): Provides high-level APIs for creating and manipulating graphs, suitable for most users.
+
+- **`@ts-graphviz/core`**: Contains core implementations of models and functions, used internally and available for advanced use.
+
+- **`@ts-graphviz/common`**: Aggregates Graphviz domain knowledge, providing type definitions, constants, and utilities. Supports use cases like extending custom types and attributes.
+
+- **`@ts-graphviz/ast`**: Offers tools for parsing, manipulating, and generating DOT language graphs at the AST level.
+
+- **`@ts-graphviz/adapter`**: Executes Graphviz commands in various runtime environments (Node.js, Deno) and converts DOT strings to images.
+
+- **`@ts-graphviz/react`**: Allows defining graphs using React's declarative UI paradigm, expressing DOT language models with JSX.
+
+## Dependency Graph
+
+The relationships between packages can be visualized as follows:
+
+![Dependency Graph](./img/dependency-graph.svg)
+
+This modular architecture ensures:
+
+- **Maintainability**: Individual packages can be maintained and updated without affecting others.
+
+- **Flexibility**: Users can select only the packages needed for their specific use cases.
+
+- **Extensibility**: Facilitates the addition of new features or packages as the library evolves.
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/03-versioning-policy.md b/docs/ts-graphviz/12-architecture-and-design-principles/03-versioning-policy.md
@@ -0,0 +1,47 @@
+
+# Versioning Policy
+
+## Overview
+
+**ts-graphviz** follows [**Semantic Versioning 2.0**](https://semver.org/) to ensure consistency and predictability. This policy clarifies how we manage breaking changes, especially those related to runtime support, and what users can expect when using **ts-graphviz**.
+
+## Semantic Versioning
+
+Version numbers are formatted as **MAJOR.MINOR.PATCH**, with changes classified as follows:
+
+- **MAJOR**: Introduces backward-incompatible changes.
+- **MINOR**: Adds functionality in a backward-compatible manner.
+- **PATCH**: Fixes bugs in a backward-compatible manner.
+
+---
+
+## Exceptions: TypeScript Version Updates
+
+There are scenarios where **ts-graphviz** may deviate from strict Semantic Versioning:
+
+- **TypeScript Definitions**: Breaking changes to TypeScript type definitions may occur between minor versions due to:
+  - TypeScript introducing breaking changes in its own minor updates.
+  - Adopting features available only in newer TypeScript versions, which may raise the minimum required TypeScript version.
+
+:::tip
+For TypeScript projects, we recommend pinning the **ts-graphviz** minor version to control upgrade timing and compatibility testing.
+:::
+
+---
+
+## Information Sharing
+
+We are committed to transparent communication regarding our versioning and support policies:
+
+- **Documentation and Release Notes**: All changes to the versioning policy and support levels will be documented in our official documentation and detailed in release notes.
+- **Community Engagement**: Users are encouraged to subscribe to updates or follow our repositories to stay informed about the latest developments.
+
+---
+
+## Migration Support
+
+To assist users in transitioning between versions, especially when breaking changes occur:
+
+- **Migration Guides**: We provide comprehensive migration guides outlining steps to upgrade to new major versions.
+- **Code Examples**: Examples are included to demonstrate how to adapt code to accommodate changes.
+- **Support Channels**: Users can seek assistance through community forums, issue trackers, or other support channels if they encounter difficulties during migration.
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/04-supported-environments.md b/docs/ts-graphviz/12-architecture-and-design-principles/04-supported-environments.md
@@ -0,0 +1,40 @@
+# Supported Environments
+
+To provide clarity on the environments in which **ts-graphviz** operates, we have categorized support levels:
+
+## Support Levels
+
+### Tier 1: Full Support
+
+- **Definition**: Environments that are fully supported, with comprehensive automated testing and maintenance.
+- **Environments**:
+  - **Node.js**: All active Long-Term Support (LTS) versions.
+- **Details**:
+  - We run automated tests on all LTS versions of Node.js.
+  - Full compatibility and performance are ensured.
+  - Critical issues are prioritized for fixes.
+
+### Tier 2: Active Support
+
+- **Definition**: Environments that receive active support with limited automated testing.
+- **Environments**:
+  - **Deno**: Latest stable version.
+  - **Node.js Current Release**: The latest Node.js release outside the LTS schedule.
+- **Details**:
+  - Automated tests are conducted on the latest version of Deno to confirm functionality.
+  - Compatibility is maintained, and issues are addressed.
+
+### Tier 3: Community Support
+
+- **Definition**: Environments that are not officially tested but are supported on a best-effort basis.
+- **Environments**:
+  - **Modern Browsers**: Latest versions of major browsers, including:
+    - Google Chrome
+    - Mozilla Firefox
+    - Microsoft Edge
+    - Apple Safari
+- **Details**:
+  - Installation methods are provided.
+  - No automated testing is performed.
+  - Issues reported by users will be addressed.
+  - Targeting the latest versions ensures compatibility with modern web standards.
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/05-security-policies.md b/docs/ts-graphviz/12-architecture-and-design-principles/05-security-policies.md
@@ -0,0 +1,29 @@
+# Security Policies
+
+## Purpose and Importance
+
+In today's software development landscape, **open-source software (OSS)** plays an indispensable role in building applications. According to the **Open Source Security Foundation (OpenSSF)**, **70% to 90%** of modern applications consist of OSS components, and the complexity of their dependencies is increasing daily.
+
+### The Impact and Responsibility of ts-graphviz
+
+**ts-graphviz** is a widely used library with over 2 million downloads per month, impacting a broad range of applications. Even users who do not directly interact with ts-graphviz are affected through software that depends on it.
+
+> ![Dependency](https://imgs.xkcd.com/comics/dependency.png)
+>
+> *An illustration of software dependencies (Source: [xkcd.com/2347](https://xkcd.com/2347/))*
+
+This illustration highlights how modern software relies on numerous underlying components.
+
+**Ensuring the security of ts-graphviz is crucial because vulnerabilities can cascade through dependencies, potentially affecting countless applications.**
+
+## Commitment to Security
+
+ts-graphviz is committed to more than just providing secure source code. We implement **comprehensive security measures** that consider the **entire software supply chain**. This dedication ensures that users can confidently adopt ts-graphviz, knowing it contributes to building secure and reliable applications.
+
+## Software Supply Chain Security
+
+Recognizing that modern applications are heavily dependent on open-source software, we implement practices that safeguard against vulnerabilities throughout the dependency chain.
+
+## Reporting Vulnerabilities
+
+We encourage users and security researchers to report any vulnerabilities or security concerns. Prompt reporting allows us to address issues swiftly, maintaining the integrity and security of the library.
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/_category_.json b/docs/ts-graphviz/12-architecture-and-design-principles/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Architecture and Design Principles",
+  "link": {
+    "type": "generated-index"
+  }
+}
+
diff --git a/docs/ts-graphviz/12-architecture-and-design-principles/index.md b/docs/ts-graphviz/12-architecture-and-design-principles/index.md
