Development Workflow & PR Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• README.md
• package.json
• .github/pull_request_template.md
• .github/PULL_REQUEST_TEMPLATE/feature.md
• .github/PULL_REQUEST_TEMPLATE/bug_fix.md

Introduction

The Poixpixel Discord Bot project maintains a structured development workflow to ensure code quality, consistency, and a safe community environment. This workflow encompasses everything from the initial local environment setup and branching strategy to strict commit message conventions and a comprehensive Pull Request (PR) review process. Contributors are expected to adhere to these guidelines to facilitate efficient integration of new features and bug fixes.

The scope of these guidelines includes the technical requirements for TypeScript development, formatting standards using Prettier, and behavioral expectations defined in the Code of Conduct. All contributions are governed by the Apache License 2.0.
Sources: CONTRIBUTING.md:1-25, CODE_OF_CONDUCT.md:1-15, package.json:5

Local Development Setup

To contribute to the project, developers must configure a local environment that mirrors the project's tech stack. The bot requires Node.js (version 22 or higher) and uses Yarn (version 4.10.3+) for dependency management via Corepack.

Prerequisites and Initialization

1. Environment: Ensure Node.js >= 22.0.0, PostgreSQL, Redis, and Git are installed.
2. Installation: Run corepack enable followed by yarn install.
3. Configuration: Copy config.example.json to config.json and populate it with Discord bot tokens and database credentials.
4. Database: Execute npx drizzle-kit migrate to set up the schema.
   Sources: CONTRIBUTING.md:40-75, package.json:71-73

Common Development Commands

The project uses several NPM scripts to manage the build and runtime lifecycle:

Command	Description
yarn dev	Compiles TypeScript and starts the bot with command deployment.
yarn no-deploy	Starts the bot without re-deploying slash commands to Discord.
yarn lint	Runs ESLint and checks for TypeScript compilation errors.
yarn format:fix	Automatically formats code using Prettier.
yarn compile	Runs the TypeScript compiler (tsc).
Sources: package.json:11-20, README.md:18-35

Branching and Version Control

The project follows a simplified Git workflow designed for integration and stability.

Branching Strategy

• main: The protected branch containing production-ready code.
• development: The integration branch for ongoing work.
• Feature Branches: Created from main, following the naming convention username/category-description.

Naming Examples:

• username/feature-name
• username/fix-issue
• username/docs-update
  Sources: CONTRIBUTING.md:155-175

Commit Message Guidelines

The project enforces the Conventional Commits specification. Commits are validated in CI using commitlint.

Format: <type>(<scope>): <subject>

Type	Use Case
feat	A new feature or command.
fix	A bug fix.
refactor	Code changes that neither fix a bug nor add a feature.
chore	Maintenance tasks like updating dependencies.
docs	Changes to documentation.
perf	Changes that improve performance.
Sources: CONTRIBUTING.md:177-210, package.json:49-50

Pull Request Process

The PR process is the final gate for code quality. Contributors must use the provided templates and ensure all checks pass.

Submission Workflow

This diagram illustrates the lifecycle of a contribution from local development to the final merge.

The workflow ensures that code is linted and formatted before it ever reaches a maintainer for review.
Sources: CONTRIBUTING.md:118-140

PR Templates and Types

The repository utilizes specialized templates located in .github/PULL_REQUEST_TEMPLATE/. Selecting the correct template via the template query parameter helps maintainers understand the context of the change.

• feature.md: For new commands or features.
• bug_fix.md: For resolving regressions or bugs.
• refactor.md: For code cleanup without behavior changes.
• docs.md: For documentation updates.
  Sources: CONTRIBUTING.md:142-153

Coding Standards and Patterns

All code must be written in TypeScript, adhering to strict typing and specific architectural patterns.

Core Implementation Rules

• Path Aliases: Use @/ to reference the src/ directory (e.g., import { foo } from '@/util/helpers.js').
• File Extensions: All imports must include the .js extension for TypeScript path resolution.
• Command Structure: Commands must export a default object satisfying the Command type, containing a SlashCommandBuilder and an execute function.

Example Command Pattern

import { SlashCommandBuilder } from 'discord.js';
import type { Command } from '@/types/CommandTypes.js';

export default {
  data: new SlashCommandBuilder()
    .setName('example')
    .setDescription('Standard command pattern'),

  async execute(interaction) {
    // Implementation with error handling
  },
} satisfies Command;

Sources: CONTRIBUTING.md:213-245

Community and Security

The development workflow is supplemented by policies on conduct and security reporting.

Reporting Security Vulnerabilities

Security issues must never be reported via public GitHub issues. Instead, contributors should use GitHub Security Advisories. The maintainers aim to acknowledge reports within 72 hours.
Sources: SECURITY.md:7-15

Code of Conduct Enforcement

The project maintainers are responsible for enforcing the standards of behavior. Reports of harassment or unacceptable behavior are handled privately via conduct@poixpixel.ahmadk953.org.
Sources: CODE_OF_CONDUCT.md:38-65

Conclusion

By following these Development Workflow & PR Guidelines, contributors help maintain the integrity and scalability of the Poixpixel Discord Bot. Adherence to Conventional Commits, TypeScript strictness, and the structured PR process ensures that the bot remains stable and easy to maintain as it moves toward a production-ready state.