Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive guide for contributing to the @opensky/remotes package. The package provides SvelteKit helper utilities, specifically createValidation and createEnhancedForm, to improve the experience of working with remote form functions. Adhering to these guidelines ensures consistency, quality, and maintainability of the codebase.
The contribution process covers setting up the development environment, following established coding standards, formatting commit messages correctly, and using the provided scripts for testing and building the package.
Development Environment and Workflow
To contribute, you will need a development environment with Node.js. The project relies on several key dependencies and scripts to manage the development lifecycle.
Dependencies
The project is built with Svelte 5 and SvelteKit. Key dependencies are managed in package.json.
- Peer Dependencies: Contributors should be aware of the required peer dependencies for the package to function in a host project.
@sveltejs/kit:^2.27.0svelte:^5.0.0
- Development Dependencies: The development workflow is supported by a set of tools for linting, formatting, type-checking, and building.
eslint: For code linting.prettier: For code formatting.typescript: For static typing.svelte-check: For checking Svelte components.vite: The build tool used by SvelteKit.
Sources: packages/remotes/package.json:16-41
NPM Scripts
A set of npm scripts is provided to streamline common development tasks.
| Script | Description |
|---|---|
lint | Runs Prettier to check formatting and ESLint to analyze code for issues. |
format | Formats all project files using Prettier. |
check | Synchronizes SvelteKit types and runs svelte-check with the project's tsconfig.json. |
check:watch | Runs check in watch mode for continuous checking. |
build | Builds the project for development and then runs the prepack script. |
prepack | Prepares the package for publishing by running svelte-package and publint. |
dev | Starts the Vite development server. |
Sources: packages/remotes/package.json:65-73
Contributor Workflow
The following diagram illustrates the recommended workflow for contributors.
This diagram shows the standard fork/branch and pull request workflow, emphasizing the local validation steps.
Sources: packages/remotes/package.json:65-73
Coding Standards
The project enforces strict coding standards using TypeScript, ESLint, and Prettier to maintain code quality and consistency.
TypeScript Configuration
The project uses a strict TypeScript configuration to ensure type safety.
strict: true: Enables all strict type-checking options.module: "NodeNext"andmoduleResolution: "bundler": Modern module settings for Node.js environments.forceConsistentCasingInFileNames: true: Prevents issues on case-sensitive file systems.
Sources: packages/remotes/tsconfig.json:5-12
Linting with ESLint
ESLint is configured in packages/remotes/eslint.config.js to enforce a consistent coding style. The configuration is composed of several layers.
The diagram below shows how different ESLint configurations are combined.
Key aspects of the ESLint setup include:
- Base Configurations: It extends recommended rules from
@eslint/js,typescript-eslint, andeslint-plugin-svelte. - Prettier Integration:
eslint-config-prettieris used to disable ESLint rules that conflict with Prettier. - Globals: Browser and Node.js global variables are enabled.
- Rule Overrides: The
no-undefrule is turned off for TypeScript files, as TypeScript's own checks are preferred for detecting undefined variables. - Svelte Files: Specific parser options are configured for
*.svelte,*.svelte.ts, and*.svelte.jsfiles to enable TypeScript parsing within Svelte components.
// packages/remotes/eslint.config.js:22-26
rules: {
// typescript-eslint strongly recommend that you do not use the no-undef lint rule on TypeScript projects.
// see: https://typescript-eslint.io/troubleshooting/faqs/eslint/#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
'no-undef': 'off'
}
Sources: packages/remotes/eslint.config.js:11-40
Commit Message Format
Commit messages must follow a specific format to ensure clarity and to support automated changelog generation. The format is based on conventional commits.
A commit message should consist of:
- A short, imperative subject line: Summarizes the change.
- A body: Explains the "why" behind the change, not the "how".
- A list of key improvements: Bullet points detailing the user-facing changes.
- A list of breaking changes: Clearly marked with
Breaking changes:.
The following is an example of a well-formed commit message:
Move delayMs and timeoutMs to createEnhancedForm options
This change moves the timing configuration from the enhance callback to the createEnhancedForm creation options, enabling type-safe conditional states and callbacks.
Key improvements:
- delayMs and timeoutMs are now specified at creation time
- State type is conditional: 'delayed' only exists if delayMs is set, 'timeout' only exists if timeoutMs is set
- Callbacks (onDelay, onTimeout) are type-checked: only allowed when the corresponding timing option is provided at creation
- Both callbacks remain optional when their timing options are set
- delayMs and timeoutMs are independent of each other
Breaking changes:
- Timing options must now be passed to createEnhancedForm() instead of form.enhance()
- State accessors (delayed, timeout) are only available when the corresponding timing option is configured
Sources: commit-message.txt
Package Publishing
While contributors may not publish packages directly, understanding the process is important. The prepack script is run before npm publish.
Publishing Workflow
This diagram shows the sequence of commands executed to prepare the package for publishing.
Sources: packages/remotes/package.json:65, 71
The files array in package.json specifies that only the dist directory is included in the final published package, ensuring a lean package size.
Sources: packages/remotes/package.json:43-47
Summary
Contributors are expected to follow the established workflow and coding standards. This includes setting up the environment correctly, using the provided npm scripts for linting and checking, and adhering to the commit message format. By following these guidelines, you help maintain the high quality and consistency of the @opensky/remotes package.
Sources: README.md, packages/remotes/package.json