Public/automatic
1
0
Fork 0
mirror of https://github.com/vladmandic/automatic synced 2026-09-20 01:31:13 +02:00
Code Issues Packages Projects Releases Wiki Activity

wiki add dev section 

Signed-off-by: Vladimir Mandic <mandic00@live.com>
Vladimir Mandic
2026-05-20 20:09:25 +02:00
parent dbf401770a
commit 121b0612a9
11 changed files with 297 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING
-27
@@ -1,27 +0,0 @@
# Contributing Guidelines
Pull requests from everyone are welcome
Procedure for contributing:
- Select SD.Next `dev` branch:
<https://github.com/vladmandic/sdnext/tree/dev>
- Create a fork of the repository on github
In a top right corner of a GitHub, select "Fork"
Its recommended to fork latest version from main branch to avoid any possible conflicting code updates
- Clone your forked repository to your local system
`git clone https://github.com/<your-username>/<your-fork>`
- Make your changes
- Test your changes
- Lint your changes against code guidelines
- `ruff check`
- `pylint <folder>/<filename>.py`
- Push changes to your fork
- Submit a PR (pull request)
- Make sure that PR is against `dev` branch
- Update your fork before createing PR so that it is based on latest code
- Make sure that PR does NOT include any unrelated edits
- Make sure that PR does not include changes to submodules
Your pull request will be reviewed and pending review results, merged into `dev` branch
Dev merges to main are performed regularly and any PRs that are merged to `dev` will be included in the next main release
Dev-AICoding.md
+33
@@ -0,0 +1,33 @@
# AI Coding Guide
SD.Next is equipped with AI intructions and skills to assist developers in coding tasks.
For typical coding tasks, AI tools will automatically select the appropriate instruction set. However, knowing where to find these instructions and skills can help you understand how to leverage AI effectively in your development workflow.
> [!NOTE]
> AI guides and skills are written in model-agnostic language, meaning they can be used with any AI tool that supports the required capabilities. The instructions and skills are designed to be flexible and adaptable to different AI platforms.
## Instructions
- `AGENTs.md`
Starting point that links to all relevant instructions and skills for core and UI development.
- `.github/copilot-instructions.md`
General project guidelines, tools, structure, style, and conventions.
- `.github/instructions/core.instructions.md`
Instructions for core development tasks.
- `.github/instructions/ui.instructions.md`
Instructions for UI development tasks.
## Skills
- `.github/skills/README.md`
Overview of available skills for various coding tasks.
- `.github/skills/*/SKILL.md`
Specific skills for various coding tasks.
## Guidelines
- `wiki/Dev-Home.md`
Overview of all developer resources and guides.
- `wiki/Dev-*.md`
Additional guidelines and resources for developers.
Docs.md → Dev-Docs.md
Extensions.md → Dev-Extensions.md
+1 -1
@@ -1,4 +1,4 @@
# Extensions Development
# Dev: Script & Extensions Guide
## Common Mistakes
Dev-GettingStarted.md
+99
@@ -0,0 +1,99 @@
# Dev: Getting Started
We welcome contributions from everyone!
This guide explains how to fork the repo, prepare your branch, run repo-specific checks, and submit a pull request.
## Prerequisites
- Git
- Node.js (supported version is `>=22.0.0`)
- Python 3.10+
- An active GitHub account
## 1. Fork and clone
> [!IMPORTANT]
> All contributions should be made against the [`dev`](https://github.com/vladmandic/sdnext/tree/dev) branch, which is the main development branch for SD.Next.
### Select branch
Dev: <https://github.com/vladmandic/sdnext/tree/dev>
### Create fork
Create a fork of the repository on GitHub. In the top-right corner of the repository page, select **Fork**.
### Clone your fork
Clone your fork locally:
```bash
git clone https://github.com/<your-username>/sdnext.git
cd sdnext
git checkout dev
```
### Optional: Create a branch
Creating a feature branch is optional but recommended, especially if you plan to work on multiple PRs or want to keep your changes organized.
> [!TIP]
> Good branch names are `feature/your-feature-name` or `fix/issue-description`.
> Avoid generic names like `my-changes` or `update-code`.
```bash
git checkout -b my-feature-branch
```
## 2. Install dependencies
Install the project dependencies:
> [!TIP]
> `pnpm` is recommended for faster installs, but default `npm` also works:
```bash
npm install
```
## 3. Make your changes
Edit only the files needed for your contribution. Avoid unrelated changes and do not include submodule updates unless they are part of your work.
## 4. Review your scope
Check the files you changed:
```bash
git status
```
Confirm that your branch includes only the intended changes and does not contain unrelated edits or submodule updates. If you see any unintended changes, you can reset them before committing.
## 5. Lint and validate
SD.Next has a comprehensive linting and validation workflow to ensure code quality. Run the following command to check your changes:
Run the project lint workflow before submitting your PR:
> [!IMPORTANT]
> Make sure to fix any linting errors before submitting your PR.
```bash
npm run lint
```
This command runs:
- `precommit` for formatting and pre-commit checks
- `eslint` for JavaScript/TypeScript linting
- `tsc` for TypeScript type checks
- `ruff` for Python linting
- `pylint` for Python static analysis
## 6. Commit and submit
- Commit your changes with a clear message
- Push your branch to your fork
- Open a PR against `dev`.
Your PR will be reviewed and, once approved, merged into `dev`. Changes merged to `dev` are included in the next main release.
Dev-Home.md
+18
@@ -0,0 +1,18 @@
# Development Home
This section contains guides and resources for developers contributing to the project. Whether you're fixing a bug, adding a new feature, creating an extension, doing UI design, or improving documentation, you'll find everything you need to get started here.
- Creating a pull request?
See [Getting Started](Dev-GettingStarted) for step-by-step instructions on how to fork the repo, prepare your branch, run checks, and submit your PR.
- Want to familiarize yourself with the code structure?
See [Code Structure](Dev-Structure) for an overview of the main folders, repositories, and how they relate to each other.
- Want to contribute to documentation or make changes?
See [Wiki & Docs](Dev-Docs) for how to edit existing articles, create new ones, and contribute to the documentation site.
- Want to customize the UI?
See [User Themes](Dev-Theme) for how to create and contribute custom themes for both the standard and modern UI.
- Interested in creating a new extension or script?
See [Script & Extensions Guide](Dev-Extensions) for best practices and tips on developing *extensions* and scripts.
- Interested in improving the UI components?
See [UI Guide](Dev-UI) for how to build and contribute to the core, modern, and kanvas UI components.
Or you can jump right in and use **AI** for coding? See [AI Coding Guide](Dev-AICoding) for how to leverage AI tools.
Locale.md → Dev-Locale.md
Dev-Structure.md
+68
@@ -0,0 +1,68 @@
# Dev: Code Structure
SD.Next is organized as core repo with multiple submodules for different components where each submodule is a separate repository.
## Core repo
Repo: <https://github.com/vladmandic/sdnext>
The core repo contains the main application code and default UI components
Entire server-side code is written in **Python**.
UI components are written in **TypeScript**.
Folders:
- `modules/` - main application code
this is core of SD.Next
- `pipelines` - model pipeline definitions and related code
loaders and model-specific code
- `scripts/` - additional scripts available in the application
good place is to add new scripts
- `ui/` - UI components and related code
client-side code for core UI components and StandardUI
- `extensions-builtin/` - built-in extensions included in the application
look here for ModernUI and Kanvas
- `cli/` - command-line interface tools and api usage examples
- `configs/` - model configuration files and templates
- `data/` - json data files used for preconfigured items and models
- `models/` - model files and related assets
- `outputs/` - output files generated by the application
- `extensions/` - 3rd party extensions installed by users
this is where user-installed extensions are located
- `test/` - test utilities
## Wiki
Wiki repo contains documentation and guides for developers and users.
- Repo: <https://github.com/vladmandic/sdnext/wiki>
- Folder: `wiki/`
Wiki is also used to automatically build online documentation: <https://vladmandic.github.io/sdnext-docs/>.
## ModernUI
ModernUI is the default UI for SD.Next.
- Repo: <https://github.com/binaryQuantumSoul/sdnext-modernui>
- Folder: `extensions-builtin/sdnext-modernui/`
## Kanvas
Kanvas is a UI extension that provides a canvas-based interface for image editing and masking.
- Repo: <https://github.com/vladmandic/sdnext-kanvas>
- Folder: `extensions-builtin/sdnext-kanvas/`
## Data
Data repo is backend repo that provides data for the application such as 3rd party extension lists.
It runs fully automated workflows and typically is not cloned locally.
- Repo: <https://github.com/vladmandic/sd-data>
## Docs
Docs repo is used to build online documentation from wiki content.
It runs fully automated workflows and typically is not cloned locally.
- Repo: <https://github.com/vladmandic/sdnext-docs>
Theme-User.md → Dev-Theme.md
+1 -1
@@ -11,7 +11,7 @@ Custom themes require only basic CSS knowledge—each theme is a single CSS file
## Standard UI
- Themes are CSS files in the `/javascript` folder
- Themes are CSS files in the `/ui/css` folder
- Copy an existing theme (e.g., `black-teal.css` or `light-teal.css`) to a new file (e.g., `my-theme.css`)
- Edit `my-theme.css` to customize colors, fonts, sizes, borders, padding, margins, etc.
- The new theme will be selectable in the UI after a server restart
Dev-UI.md
+76
@@ -0,0 +1,76 @@
# Dev: UI Guide
UI development is a key part of SD.Next, and we welcome contributions to improve the user interface.
UI components are written in **TypeScript** and located in 3 separate locations within SD.Next:
- **Core**:
Contains core UI components and StandardUI
Folder: `ui/`
Repo: <https://github.com/vladmandic/sdnext>
- **ModernUI**:
Contains ModernUI UI components and related code
Folder: `extensions-builtin/sdnext-modernui/`
Repo: <https://github.com/binaryQuantumSoul/sdnext-modernui>
- **Kanvas**:
Contains Kanvas UI components and related code
Folder: `extensions-builtin/sdnext-kanvas/`
Repo: <https://github.com/vladmandic/sdnext-kanvas>
> [!NOTE]
> Depending on the scope of your changes, your contribution may involve one or more of these repositories.
> [!IMPORTANT] Any changes to the code requires rebuild to be visible in the application.
> [!WARNING] Do not edit built files, always edit source files and run the build command to generate the built files.
## Requirements
All UI work requires that NodeJS is installed
Install requirements:
```bash
npm install
```
## Building
All build commands are defined in `package.json` and can be run with `npm run <command>`.
To create production builds:
- `build:core` - builds core UI components and StandardUI
- `build:modernui` - builds ModernUI components
- `build:kanvas` - builds Kanvas components
- `build` - builds all UI components
To run development builds with watch mode that automatically rebuilds on file changes:
- `dev:ui` - builds ModernUI components with watch mode
- `dev:modernui` - builds ModernUI components with watch mode
- `dev:kanvas` - builds Kanvas components with watch mode
## Lint
[SD.Next](https://github.com/vladmandic/sdnext) uses both `ESLint, Precommit and Typescript` checks to maintain code quality and enforce coding standards.
> [!IMPORTANT]
> Linting is required for all contributions and can be run with
- `tsc:core` - runs TypeScript checks for core UI components
- `tsc:modernui` - runs TypeScript checks for ModernUI components
- `tsc:kanvas` - runs TypeScript checks for Kanvas components
- `tsc` - runs TypeScript checks for all UI components
- `eslint:core` - runs ESLint for core UI components
- `eslint:modernui` - runs ESLint for ModernUI components
- `eslint:kanvas` - runs ESLint for Kanvas components
- `eslint` - runs ESLint for all UI components
- `precommit` - runs Precommit checks for all UI components
> [!TIP]
> `npm run ui` runs all UI checks and a full build.
> It is recommended before submitting a PR.
## Paths
- **Core**: source `ui/` -> target `ui/dist/`
- **ModernUI**: source `extensions-builtin/sdnext-modernui/src/` -> target `extensions-builtin/sdnext-modernui/javascript/`
- **Kanvas**: source `extensions-builtin/sdnext-kanvas/src/` -> target `extensions-builtin/sdnext-kanvas/javascript/` & target `extensions-builtin/sdnext-kanvas/dist/`
Themes.md
+1 -1
@@ -41,7 +41,7 @@ After setting a theme type, `standard` and `modern` themes can be switched live
## Creating Custom Themes
See [User Themes](Theme-User) for details on creating custom themes
See [User Themes](Dev-Theme) for details on creating custom themes
## Available Themes