CONTRIBUTING.md

Contributing to apps-script-utils

Great that you are here and you want to contribute to apps-script-utils!

Contents

• Contributing to apps-script-utils
  • Contents
  • Code of Conduct
  • Directory Structure
  • Development Setup
    • Requirements
      • Node.js
      • npm
    • Actual Setup
  • Development Cycle
    • Basic Development Workflow
    • Commit Message Guidelines
    • Community PR Guidelines
      • 1. General Requirements
      • 2. PR Specific Requirements
    • Test Suite
  • Roadmap
  • License

Code of Conduct

This project and everyone participating in it are governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to stoianov.maksym@gmail.com.

Directory Structure

The project is organized as follows:

• config/ — Configuration files for build tools and environment.
• docs/ — Documentation and assets.
• scripts/ — Utility scripts for maintenance and development.
• src/ — Source code of the library. Organized into logical modules like appsscript/, lang/, net/, etc.
• test/ — Test suites mirroring the src structure.

Development Setup

Requirements

Node.js

Node.js (latest LTS recommended) is required for development.

npm

npm is used for dependency management and scripts.

Actual Setup

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/<your_username>/apps-script-utils.git
   cd apps-script-utils

3. Add upstream remote:

   git remote add upstream https://github.com/MaksymStoianov/apps-script-utils.git

4. Install dependencies:

   npm install

5. Build the project:

   npm run build

Development Cycle

Basic Development Workflow

1. Hack, hack, hack.
2. Ensure code quality:

   npm run lint:fix
   npm run format:fix

3. Run tests:

   npm run test

4. Commit your changes following the Commit Message Guidelines and create a Pull Request.

Commit Message Guidelines

We follow the Conventional Commits specification. Structured commit messages allow automated tools like Release Please to generate changelogs and determine semantic version bumps automatically.

Commit Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Commit Types

Type	Description	Release Impact
feat	A new feature	Minor (0.x.0)
fix	A bug fix	Patch (0.0.x)
docs	Documentation changes only	None
style	Formatting, missing semi-colons, whitespace (no code change)	None
refactor	Code restructuring without adding features or fixing bugs	None
perf	Performance improvements	Patch / None
test	Adding or updating tests	None
build	Changes to build configuration or dependencies	None
ci	Changes to CI workflows and scripts	None
chore	Routine tasks, maintenance, or tooling changes	None

Scopes

The scope specifies the affected module or package (e.g., core, decorators, router, service, domain, pipes, validation, config). Scope is optional but encouraged for clarity.

Breaking Changes

Breaking changes should be indicated by an exclamation mark ! before the colon in the header or by a BREAKING CHANGE: footer. This triggers a Major version bump (x.0.0).

feat(core)!: drop support for legacy handler format

Rules & Best Practices

• Imperative mood: Use the imperative, present tense ("add", "fix", "change", not "added", "fixes", "changing").
• Case: Start the description in lowercase.
• Punctuation: Do not end the description with a period (.).
• Issue references: Reference relevant issue numbers when applicable (e.g., (fixes #100)).

Examples

• feat(decorators): add @SheetController and @DocController
• fix(router): resolve route inheritance issues in controllers (fixes #100)
• docs: update README with new response features
• refactor(core): cleanup enums, types and repository helpers
• test: add unit tests for ResponseBuilder
• chore: update dependencies

Community PR Guidelines

1. General Requirements

• Follow the Style Guide: Adhere to the project's coding standards (TypeScript, Prettier, ESLint).
• TypeScript Compliance: Use strict TypeScript typing. Avoid any where possible.
• Documentation: Use JSDoc/KDoc comments for all exported functions. Include @param, @returns, @since, and @version tags where applicable.
• Avoid Repetitive Code: Reuse existing utilities and patterns.
• Testing: PRs must include tests. Use the @/ alias to import from the src/ directory.
• Typos: Use a spell-checker to avoid typos in code and documentation.

2. PR Specific Requirements

• Small PRs: Focus on a single feature or fix per PR.
• Naming: Use clear and descriptive PR titles.
• CHANGELOG: Do not modify CHANGELOG.md manually. It is updated automatically during the release process.

Test Suite

The project uses Vitest for testing.

• Run all tests:

  npm run test

• Watch mode:

  npm run dev

Roadmap

The current vision for the project's development can be found in the Roadmap. Please note that the roadmap is for informational purposes and is subject to change.

License

By contributing to apps-script-utils, you agree that your contributions will be licensed under the Apache-2.0 License.