Skip to content
atlcli

Contributing

Contributing

Section titled “Contributing”

Guidelines for contributing to atlcli.

Development Setup

Section titled “Development Setup”

Prerequisites

Section titled “Prerequisites”
  • Bun v1.0+
  • Node.js 18+ (for some tooling)
  • An Atlassian Cloud account for testing

Clone and Build

Section titled “Clone and Build”
Terminal window
git clone https://github.com/BjoernSchotte/atlcli.git
cd atlcli
bun install
bun run build

Run Tests

Section titled “Run Tests”
Terminal window
bun test

Project Structure

Section titled “Project Structure”
atlcli/
├── apps/
│   └── cli/              # CLI application
│       └── src/
│           ├── commands/ # Command handlers
│           └── index.ts  # Entry point
├── packages/
│   ├── core/             # Shared utilities
│   ├── confluence/       # Confluence API client
│   └── jira/             # Jira API client
├── docs/                 # Documentation (this site)
└── spec/                 # Internal specs and roadmaps

Coding Standards

Section titled “Coding Standards”

TypeScript

Section titled “TypeScript”
  • Use strict TypeScript settings
  • Prefer explicit types over any
  • Use interfaces for public APIs

Formatting

Section titled “Formatting”

The project uses Biome for linting and formatting:

Terminal window
bun run lint
bun run format

Commits

Section titled “Commits”

Follow Conventional Commits:

feat(jira): add worklog timer mode
fix(confluence): handle empty pages
docs: update authentication guide

Pull Requests

Section titled “Pull Requests”
  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/my-feature)
  3. Make your changes
  4. Run tests (bun test)
  5. Commit with conventional commit message
  6. Push and open a PR

PR Guidelines

Section titled “PR Guidelines”
  • Keep PRs focused on a single change
  • Include tests for new functionality
  • Update documentation if needed
  • Ensure CI passes

Architecture

Section titled “Architecture”

Monorepo Structure

Section titled “Monorepo Structure”

atlcli uses a monorepo with:

  • apps/cli - The CLI application
  • packages/* - Shared libraries

API Clients

Section titled “API Clients”

Each Atlassian product has its own package:

  • @atlcli/confluence - Confluence REST API
  • @atlcli/jira - Jira REST API

Clients handle authentication, request/response, and error handling.

Command Pattern

Section titled “Command Pattern”

Commands follow a consistent pattern:

async function handleCommand(args: string[], flags: Flags, opts: Options): Promise<void> {
  // 1. Parse and validate input
  // 2. Call API client
  // 3. Format and output result
}

Releasing

Section titled “Releasing”

Releases are automated via the release script:

Terminal window
bun scripts/release.ts patch    # 0.16.0 → 0.16.1
bun scripts/release.ts minor    # 0.16.0 → 0.17.0
bun scripts/release.ts major    # 0.16.0 → 1.0.0

What the Release Script Does

Section titled “What the Release Script Does”
  1. Validates clean working directory and main branch
  2. Runs tests and type checking
  3. Bumps version in package.json
  4. Generates the changelog with git-cliff, crediting contributors and issue reporters
  5. Creates commit and tag
  6. Pushes to origin (triggers GitHub release workflow)
  7. Waits for release artifacts
  8. Triggers Homebrew tap update

Options

Section titled “Options”
  • --dry-run - Print the release plan and exit; makes no changes
  • --preview - Render the changelog entry (including the Thanks section) and exit; makes no changes
  • --skip-tests - Skip test step (use with caution)

Prerequisites

Section titled “Prerequisites”
  • GitHub CLI authenticated (gh auth login)
  • On main branch with clean working directory

Example: Preview a Release

Section titled “Example: Preview a Release”

Both --dry-run and --preview print and exit without changing anything, so no rollback is needed:

Terminal window
# Show the step-by-step release plan
bun scripts/release.ts minor --dry-run


# Render the changelog entry, including the Thanks section
bun scripts/release.ts minor --preview

Reporting Issues

Section titled “Reporting Issues”

Use GitHub Issues for:

  • Bug reports
  • Feature requests
  • Questions

Include:

  • atlcli version (atlcli --version)
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant error messages

License

Section titled “License”

atlcli is MIT licensed. By contributing, you agree your contributions will be under the same license.

Section titled “Related Topics”
Jira and Confluence are trademarks of Atlassian Corporation Plc. atlcli is not affiliated with, endorsed by, or sponsored by Atlassian.