contributing - blueprint-site/blueprint-create GitHub Wiki

Contribution Workflow

This guide outlines the contribution workflow for the Blueprint project, including Git practices, pull request processes, and code review guidelines.

Getting Started

Before you start contributing to Blueprint, make sure you have:

  1. Created a GitHub account
  2. Cloned the repository
  3. Set up the development environment as described in the Installation Guide

Git Workflow

Blueprint follows a branch-based workflow for contributions:

Setting Up Your Repository

  1. Clone the repository locally:

    git clone https://github.com/blueprint-site/blueprint-site.github.io.git
cd blueprint-site.github.io

  2. Verify your remote:

    git remote -v

Branch Naming Convention

When creating branches, follow these naming conventions:

  • feature/short-description - For new features
  • fix/issue-description - For bug fixes
  • docs/what-changed - For documentation changes
  • refactor/component-name - For code refactoring
  • test/what-tested - For adding tests

Examples:

  • feature/addon-collections
  • fix/broken-image-upload
  • docs/api-endpoints
  • refactor/search-component

Development Workflow

  1. Sync your local repository with the remote:

    git checkout develop
git pull

  2. Create a new branch for your work:

    git checkout -b feature/your-feature-name

  3. Make your changes:

    • Follow the code standards
    • Write tests if applicable
    • Update documentation as needed

  4. Commit your changes using conventional commit messages:

    git add .
git commit -m "feat: add user collections feature"

  5. Push your branch to the repository:

    git push origin feature/your-feature-name

Conventional Commits

Blueprint uses the Conventional Commits specification for commit messages. This helps with automated versioning and changelog generation.

Format: type(scope): message

Types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Changes that don't affect code functionality (formatting, etc.)
  • refactor: Code changes that neither fix bugs nor add features
  • perf: Performance improvements
  • test: Adding or correcting tests
  • build: Changes to build process or tools
  • ci: Changes to CI configuration
  • chore: Other changes that don't modify src or test files

Examples:

  • feat(auth): add oauth login with discord
  • fix(upload): resolve image upload error
  • docs(api): update endpoint documentation
  • style(button): adjust button padding
  • refactor(search): improve search component performance

Handling Multiple Changes

If you're working on multiple changes:

  1. Create separate branches for each change
  2. Submit separate pull requests for each change
  3. Reference related pull requests in your comments

Pull Request Process

Creating a Pull Request

  1. Go to the repository
  2. Click "Pull Requests" > "New Pull Request"
  3. Select your branch as the source and develop as the target branch
  4. Click "Create Pull Request"

Writing a Good Pull Request Description

Include the following in your PR description:

  1. What does this PR do? - Brief description of the changes
  2. Related issue - Link to the GitHub issue (if applicable)
  3. Screenshots - For UI changes
  4. Testing instructions - How to test the changes
  5. Additional context - Any other relevant information

Example template:

## Description
Brief description of the changes.

## Related Issue
Fixes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Screenshots (if applicable)
![Description](url)

## Testing Instructions
1. Step 1
2. Step 2
3. Expected behavior

## Checklist
- [ ] My code follows the project's code style
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix or feature works
- [ ] New and existing tests pass with my changes

Code Review Process

For Contributors

  1. Be responsive to review comments
  2. Address all feedback before requesting a re-review
  3. Explain your reasoning when you disagree with a suggestion
  4. Test your changes thoroughly before submitting

For Reviewers

  1. Be respectful and constructive in your feedback
  2. Focus on important issues rather than minor style preferences
  3. Explain your reasoning when requesting changes
  4. Approve when ready rather than leaving PRs in limbo

Resolving Conflicts

If your PR has conflicts:

  1. Sync your local develop branch:

    git checkout develop
git pull

  2. Rebase your feature branch:

    git checkout feature/your-feature-name
git rebase develop

  3. Resolve conflicts in each file

  4. Continue the rebase:

    git add .
git rebase --continue

  5. Force push your updated branch:

    git push --force origin feature/your-feature-name

Handling Feedback

Addressing Review Comments

  1. Make the requested changes in your local branch
  2. Commit the changes (consider using fixup commits)
  3. Push to your feature branch
  4. Respond to the comment in the PR

Using Fixup Commits

For addressing review feedback, consider using fixup commits:

git add .
git commit --fixup HEAD
git push origin feature/your-feature-name

Before final merge, squash the fixups:

git rebase -i --autosquash develop
git push --force origin feature/your-feature-name

Continuous Integration

Blueprint uses GitHub Actions for continuous integration:

  1. Linting: ESLint checks code quality
  2. Type Checking: TypeScript validation
  3. Build Check: Ensures the project builds successfully
  4. Test Runners: Runs automated tests

All CI checks must pass before a PR can be merged.

After Merge

After your PR is merged:

  1. Delete your feature branch:

    git checkout develop
git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

  2. Update your local develop branch:

    git pull

  3. Celebrate your contribution! 🎉

Troubleshooting

Common Issues

  1. CI Failures:

    • Check the CI logs for specific errors
    • Run linting and tests locally before pushing

  2. Merge Conflicts:

    • Follow the conflict resolution steps above
    • If complex, consult with maintainers

  3. Stale PRs:

    • If your PR becomes outdated, rebase on the latest main

  4. Rejected PRs:

    • Read the feedback carefully
    • Address all concerns before resubmitting

Special Workflows

Hotfix Process

For critical bug fixes:

  1. Create a branch from develop: git checkout -b hotfix/critical-issue
  2. Fix the issue with minimal changes
  3. Submit a PR with "HOTFIX" in the title
  4. Request expedited review

Documentation-Only Changes

For documentation changes:

  1. Create a branch: git checkout -b docs/update-readme
  2. Make documentation changes
  3. Submit a PR with abbreviated review process

Release Process

Blueprint follows semantic versioning:

  1. Major: Breaking changes
  2. Minor: New features, non-breaking
  3. Patch: Bug fixes, non-breaking

The release process is handled by maintainers, who will:

  1. Merge PRs into develop
  2. Merge develop into main when ready for release
  3. Create a new version tag
  4. Generate release notes
  5. Deploy to production

Additional Resources

Questions and Support

If you have questions about contributing:

  1. Check the documentation
  2. Search for existing issues
  3. Join our Discord server
  4. Ask in the repository discussions