Skip to content

Latest commit

 

History

History
184 lines (127 loc) · 6.4 KB

submitting-pull-requests.md

File metadata and controls

184 lines (127 loc) · 6.4 KB

Contributing to awsctl

Ready to Contribute?

Here’s how you can get started:

Commit Message Format

We follow the Conventional Commits specification for commit messages. This helps maintain clarity and consistency in the commit history and supports automated release tooling.

Format

  • Use the imperative mood in the summary (e.g., "add logging", not "added logging" or "adds logging").
  • Example: fix: handle invalid AWS profile error

Tip: You can add a scope to clarify the area affected, e.g., feat(rds): add multi-AZ support

Allowed Types

Type Description
feat A new feature (correlates with MINOR in SemVer)
fix A bug fix (correlates with PATCH in SemVer)
docs Documentation-only changes
style Code style changes (formatting, white-space, etc., no code logic impact)
refactor Code changes that neither fix a bug nor add a feature
perf Code changes that improve performance
test Adding or correcting tests
build Changes to the build system or dependencies (e.g., Go modules, Docker)
ci Changes to CI configuration files and scripts (e.g., GitHub Actions)
chore Routine tasks or maintenance (e.g., dependency updates, lint fixes)
revert Reverts a previous commit

Pull Request Submission Process

Pre-Submission Checklist

Before submitting a PR:

  1. Keep It Simple:
    • Focus on solving one problem per PR.
    • Submit small, manageable pull requests.
  2. Be Thorough:
    • Add detailed comments explaining your changes.
    • Use semantic line breaks for documentation updates.
  3. Allow Maintainers to Edit: Keep the "Allow edits from maintainers" checkbox checked.

Validation Requirements

  • Ensure your PR is not a draft.
  • Pass:
    • Validation Checks
    • All Tests
  • Receive 2 approving reviews from maintainers.

Pull Request Review Cycle

Triage Process

Each PR undergoes triage to:

  • Verify all prerequisites are met.
  • Assess whether the use case aligns with project goals.
  • Assign reviewers.

Review Stages

  1. Design Review:
    • Ensures no major conflicts with the codebase.
  2. Code Review:
    • In-depth review and testing of code.
    • May require changes or clarifications.
    • Contributors are expected to be responsive to feedback.
  3. Merge:
    • Once approved, the PR is merged automatically or manually.

⚠️ During code freezes, PRs may remain unmerged until the release is complete.

Testing & Merge Workflow

  • Managed by the bot Myrmica Lobicornis:
    • Verifies GitHub checks, reviews, and mergeability.
    • Handles branch rebasing/merging if needed.
    • Adds labels like status/3-needs-merge to trigger merges.

Common Merge Labels:

  • bot/no-merge: Prevents automatic merging.
  • bot/light-review: Reduces required LGTM reviews from 2 to 1.

For more details, see the Lobicornis README.

Why Was My PR Closed?

Your PR may be closed if:

  1. Design Conflicts: The work needed to make it mergeable is too extensive.
    • Solution: Create an issue first and involve maintainers during the design phase.
  2. Out-of-Scope Enhancements: The PR is for a feature that doesn't align with project goals.
    • Solution: Always create an issue before submitting a PR.
  3. Inactivity: If no feedback is received from the contributor for over 90 days.

Why Isn’t My PR Reviewed?

Review Prioritization:

  1. Top Priority:
    • High community engagement and broad applicability.
    • Issues tagged with contributor/wanted or bug/confirmed.
  2. Secondary Priority:
    • Smaller enhancements or less critical fixes.
  3. Deprioritized:
    • Large PRs that are difficult to review.
    • PRs submitted without an associated issue.

No reviews are conducted during the final weeks of a milestone to reduce churn.

Best Practices for PRs

  • Create Issues First: Discuss your proposal with the team before starting work.
  • Submit Small PRs: Break large ideas into smaller, logical PRs.
  • Comment Everything: Assume reviewers are unfamiliar with your perspective or approach.
  • Write Tests: Include adequate tests or ask for help with them.

Need Help?

  • Re-request a review after addressing feedback.
  • Politely comment on your PR to bring visibility during triage.

Handling Feedback

  • Disagreements: If you believe a requested change is unnecessary, explain your reasoning politely.
  • Overwhelming Comments: Focus on feedback from the primary reviewer (assignee). If needed, ask to fork a new PR to clear outdated comments.

Resources for Contributors

Community Guidelines

Remember, common sense and courtesy go a long way. Contributing to AWSCTL is a collaborative effort, so let's keep the process respectful and constructive.

Together, we can make AWSCTL the best it can be!