Developer Guide

Table of Contents

• Getting Started
• Development Setup
• Development Workflow
• Project Structure
• Code Standards
• Testing
• Building
• Contributing
• Release Process

Getting Started

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or higher (Download)
• npm 9 or higher (comes with Node.js)
• Git (Download)
• Obsidian installed (Download)
• A test vault for development

Fork and Clone

• Fork the repository on GitHub
• Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/obsidian-github-projects.git
cd obsidian-github-projects

• Add the upstream remote:

git remote add upstream https://github.com/alexnodeland/obsidian-github-projects.git

Development Setup

Quick Setup with Make

# Install dependencies and set up development environment
make setup VAULT=/path/to/your/vault
Start development with auto-rebuild
make dev VAULT=/path/to/your/vault

Manual Setup

• Install dependencies:

npm install

• Build the plugin:

npm run build

• Link to your vault:

./scripts/setup-dev.sh /path/to/your/vault

Or manually copy files:

mkdir -p /path/to/vault/.obsidian/plugins/github-projects
cp main.js manifest.json styles.css /path/to/vault/.obsidian/plugins/github-projects/

• Enable the plugin:

Development Workflow

Watch Mode for Development

Use the watch mode for continuous development:

# Using Make (recommended)
make dev VAULT=/path/to/your/vault
Or using the script directly
./scripts/dev-watch.sh /path/to/your/vault

This will:

• Watch for file changes
• Automatically rebuild on changes
• Copy files to your vault
• Show notifications when ready to reload

After each rebuild:

• Press Ctrl/Cmd+R in Obsidian to reload the plugin
• Test your changes

Making Changes

• Create a feature branch:

git checkout -b feature/your-feature-name

• Make your changes

• Test your changes:

# Run tests
npm test
Run tests in watch mode
npm run test:watch
Run linter
npm run lint
Type check
npm run build

• Commit your changes:

git add .
git commit -m "feat: add awesome new feature"

Follow Conventional Commits format:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Test changes
• chore: - Build/tooling changes

• Push and create PR:

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Project Structure

obsidian-github-projects/
├── .github/
│   └── workflows/          # GitHub Actions CI/CD
├── docs/                   # Documentation
├── src/
│   ├── api/               # GitHub API client
│   │   ├── client.ts      # GraphQL client
│   │   └── queries.ts     # GraphQL queries
│   ├── state/             # State management
│   │   ├── ProjectState.ts    # Project state
│   │   └── types.ts           # Type definitions
│   ├── utils/             # Utility functions
│   │   ├── github.ts      # GitHub helpers
│   │   └── storage.ts     # Storage helpers
│   ├── views/             # UI components
│   │   ├── components/    # Reusable components
│   │   │   ├── Card.tsx
│   │   │   ├── Column.tsx
│   │   │   └── DetailModal.tsx
│   │   └── ProjectBoardView.tsx
│   ├── __tests__/         # Unit tests
│   ├── __mocks__/         # Test mocks
│   ├── main.tsx           # Plugin entry point
│   └── settings.ts        # Settings tab
├── styles.css             # Plugin styles
├── manifest.json          # Plugin manifest
├── package.json           # Dependencies
├── tsconfig.json          # TypeScript config
├── jest.config.js         # Jest config
├── esbuild.config.mjs     # Build config
└── Makefile              # Development tasks

Key Files

• src/main.tsx: Plugin entry point, registers views and commands
• src/settings.ts: Settings tab implementation
• src/api/client.ts: GitHub GraphQL API client
• src/state/ProjectState.ts: Centralized state management
• src/views/ProjectBoardView.tsx: Main board view

Code Standards

TypeScript

• Use strict mode TypeScript
• Define interfaces for all data structures
• Avoid any types - use unknown and type guards
• Use async/await for asynchronous code

Naming Conventions

• PascalCase: Classes, interfaces, types, components
• camelCase: Variables, functions, methods
• UPPER_SNAKE_CASE: Constants
• kebab-case: CSS classes, file names (when not components)

Code Style

We use ESLint for code quality. Run before committing:

npm run lint

Key rules:

• Use 2 spaces for indentation
• Use single quotes for strings
• Add semicolons at statement ends
• Max line length: 100 characters
• Use template literals for string interpolation

Component Guidelines

Preact Components:

• Use functional components with hooks
• Keep components small and focused
• Extract reusable logic into custom hooks
• Use TypeScript for prop types

Example:

interface CardProps {
  item: ProjectItem;
  onMove: (itemId: string, statusId: string) => void;
}
export function Card({ item, onMove }: CardProps) {
  // Component implementation
}

State Management

• Use Obsidian's Events for event-driven state
• Keep state immutable - create new objects for updates
• Use the ProjectState class for centralized state
• Emit events for state changes

Testing

Running Tests

# Run all tests
npm test
Run tests in watch mode
npm run test:watch
Run tests with coverage
npm test -- --coverage
Run specific test file
npm test -- Card.test.tsx

Writing Tests

Place tests in src/__tests__/ directory:

import { render, screen } from '@testing-library/preact';
import { Card } from '../views/components/Card';
describe('Card', () => {
  it('renders card title', () => {
    const item = { id: '1', title: 'Test Issue', content: '' };
    render();
    expect(screen.getByText('Test Issue')).toBeInTheDocument();
  });
});

Test Coverage

Current coverage baseline: ~12% (statements, branches, functions, lines)

Target: Gradually increase to >80% coverage

Check coverage:

npm test -- --coverage

Coverage reports are generated in coverage/ directory.

Note: Coverage thresholds are currently set to 10% to match the existing codebase. As you add features, please include tests to incrementally improve coverage.

Building

Development Build

npm run dev

This creates an unminified build with source maps for debugging.

Production Build

npm run build

This creates an optimized, minified build without source maps.

Build Output

The build process generates:

• main.js - Bundled plugin code
• main.js.map - Source map (dev build only)

Contributing

Pull Request Process

• Ensure tests pass:

   npm test
   npm run lint
   npm run build
   

• Update documentation if needed

• Add tests for new features

• Follow commit conventions (Conventional Commits)

• Create PR with clear description:

• Respond to review feedback

Code Review Guidelines

When reviewing PRs:

• Check code quality and style
• Verify tests are included and passing
• Test functionality manually
• Suggest improvements constructively
• Approve when ready to merge

Release Process

Version Numbering

We follow Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Creating a Release

• Update version in package.json and manifest.json:

npm version patch  # or minor, or major

• Update CHANGELOG.md with release notes

• Commit version bump:

git add .
git commit -m "chore: bump version to X.Y.Z"

• Create and push tag:

git tag X.Y.Z
git push origin main --tags

• GitHub Actions will automatically:

Release Checklist

• [ ] All tests passing
• [ ] Documentation updated
• [ ] CHANGELOG.md updated
• [ ] Version bumped in manifest.json and package.json
• [ ] Tag created and pushed
• [ ] GitHub release created successfully
• [ ] Community plugin submission updated (if applicable)

Development Tools

Useful Make Commands

make setup VAULT=/path    # Initial setup
make dev VAULT=/path      # Development mode
make build                # Production build
make test                 # Run tests
make lint                 # Run linter
make clean                # Clean build artifacts
make coverage             # Generate coverage report

Debugging

Browser DevTools:

• Open DevTools: Ctrl/Cmd+Shift+I
• Check Console for errors
• Use debugger statements in code
• Inspect network requests

Source Maps: Development builds include source maps for debugging TypeScript in DevTools.

Obsidian API Documentation

• Official API Docs
• API Reference
• Sample Plugin

Getting Help

• Questions: Open a GitHub Discussion
• Bugs: Open an Issue
• Ideas: Open a Feature Request

License

By contributing, you agree that your contributions will be licensed under the MIT License.