kanopi/drupalorg-contribution-helper

Drupal.org Contribution Helper

Quick assistance with drupal.org contribution workflows, git commands, and merge request creation.

When to Use This Skill

Activate this skill when the user:

• Asks "how do I contribute to drupal.org?"
• Mentions "issue fork" or "drupal merge request"
• Needs help with git.drupalcode.org commands
• Asks about drupal.org branch naming conventions
• Wants to understand the drupal.org contribution workflow

Quick Reference

drupalorg-cli Tool (Optional)

The drupalorg-cli package provides helpful shortcuts for drupal.org contribution:

# Install
curl -LO https://github.com/mglaman/drupalorg-cli/releases/latest/download/drupalorg.phar
chmod +x drupalorg.phar
sudo mv drupalorg.phar /usr/local/bin/drupalorg

# Create branch for issue (inside project directory)
drupalorg issue:branch 3456789

# Apply latest patch from issue
drupalorg issue:apply 3456789

# Generate patch from local changes
drupalorg issue:patch

# List project issues
drupalorg project:issues paragraphs

# Open issue in browser
drupalorg issue:link 3456789

Git Clone Commands

# Clone any drupal.org project
git clone [email protected]:project/{project_name}.git

# Examples
git clone [email protected]:project/paragraphs.git
git clone [email protected]:project/webform.git
git clone [email protected]:project/easy_lqp.git

Branch Naming Convention

{issue_number}-{description-slug}

Examples:
3456789-fix-validation-error
3456789-add-ckeditor5-support
3456789-update-documentation

Rules:

• Start with issue number
• Use hyphens (not underscores)
• Keep description brief but descriptive
• Maximum 255 characters

Issue Fork Remote

Remote naming follows {project}-{issue} convention to allow multiple issue forks per project:

# Add issue fork remote
git remote add {project}-{issue_number} [email protected]:issue/{project}-{issue_number}.git

# Examples
git remote add paragraphs-3456789 [email protected]:issue/paragraphs-3456789.git
git remote add easy_lqp-3456790 [email protected]:issue/easy_lqp-3456790.git

# Fetch from issue fork
git fetch {project}-{issue_number}

# Verify remotes
git remote -v

Commit Message Format

Issue #{issue_number}: {description}

Example:
Issue #3456789: Fix validation error in configuration form

Push to Issue Fork

# Push branch to issue fork
git push {project}-{issue_number} {branch_name}

# Example
git push paragraphs-3456789 3456789-fix-validation-error

Complete Workflow

1. Clone Project

# Clone to isolated location (recommended)
mkdir -p ~/.cache/drupal-contrib
git clone [email protected]:project/{project}.git ~/.cache/drupal-contrib/{project}
cd ~/.cache/drupal-contrib/{project}

2. Create Issue Fork (Manual Step Required)

Issue forks must be created via the drupal.org web UI. This cannot be automated due to CAPTCHA protection.

1. Go to: https://www.drupal.org/project/{project}/issues/{issue_number}
2. Click "Create issue fork" in the right sidebar
3. Wait for confirmation message (~10 seconds)

Note: This step cannot be done via command line or API.

3. Add Issue Fork Remote

git remote add {project}-{issue_number} [email protected]:issue/{project}-{issue_number}.git
git fetch {project}-{issue_number}

4. Create Branch

# If branch already exists on fork, checkout tracking it:
git checkout -b '{issue_number}-{description}' --track {project}-{issue_number}/'{issue_number}-{description}'

# If creating new branch:
git checkout -b {issue_number}-{description}

5. Make Changes and Commit

# Make your code changes
# ...

# Stage and commit
git add .
git commit -m "Issue #{issue_number}: {description}"

6. Push to Issue Fork

git push {project}-{issue_number} {branch_name}

7. Create Merge Request

When you push, git outputs the MR creation URL:

remote: To create a merge request for {branch}, visit:
remote:   https://git.drupalcode.org/issue/{project}-{issue}/-/merge_requests/new?...

Open that URL in your browser to complete MR creation.

Alternative: Via Web UI

1. Go to issue page on drupal.org
2. Click "Compare" button
3. Follow MR creation flow

SSH Key Setup

Check for Existing Key

ls -la ~/.ssh/id_*.pub

Generate Key if Needed

ssh-keygen -t ed25519 -C "[email protected]"

Add Key to git.drupalcode.org

1. Go to: https://git.drupalcode.org/-/user_settings/ssh_keys
2. Copy your public key: cat ~/.ssh/id_ed25519.pub
3. Paste and save

Test Connection

ssh -T [email protected]

HTTPS Fallback (If SSH Port Blocked)

If your network blocks SSH port 22, use HTTPS with a personal access token:

# Create token at: https://git.drupalcode.org/-/user_settings/personal_access_tokens
# Required scopes: read_repository, write_repository

# For clone:
git clone https://{username}:{token}@git.drupalcode.org/project/{project}.git

# For issue fork remote:
git remote add {project}-{issue} \
  "https://{username}:{token}@git.drupalcode.org/issue/{project}-{issue}.git"

Troubleshooting

"Permission denied" on push

1. Verify SSH key is added to git.drupalcode.org:

   • Go to: https://git.drupalcode.org/-/user_settings/ssh_keys
   • Add your public key

2. Verify issue fork exists:

   • Check drupal.org issue page for "Issue fork" section

3. Verify remote is correct:

   git remote -v
   # Should show: {project}-{issue} [email protected]:issue/{project}-{issue}.git
   

"Issue fork not found"

You must create the issue fork via drupal.org web UI first:

1. Go to the issue page
2. Click "Create issue fork"
3. Then add the remote

Branch Already Exists

# If local branch exists
git checkout {existing_branch}

# If remote branch exists
git fetch {project}-{issue_number}
git checkout -b {branch} --track {project}-{issue_number}/{branch}

Update Existing MR

# Make additional changes
git add .
git commit -m "Issue #{issue_number}: Additional fixes"

# Push updates (existing MR updates automatically)
git push {project}-{issue_number} {branch_name}

Best Practices

1. One issue = one branch = one MR
2. Reference issue number in every commit
3. Keep commits focused and atomic
4. Update issue status to "Needs review" after creating MR
5. Respond promptly to review feedback
6. Rebase on target branch before final merge

Example Interactions

Example 1: Quick Workflow Question

User: "How do I create a merge request for drupal.org?"

Skill response:
1. Clone the project
2. Create issue fork on drupal.org (click button in web UI - required manual step)
3. Add remote: `git remote add {project}-{issue} [email protected]:issue/{project}-{issue}.git`
4. Fetch: `git fetch {project}-{issue}`
5. Create branch: `git checkout -b {issue_number}-{description}`
6. Commit with: `Issue #{issue_number}: description`
7. Push: `git push {project}-{issue} {branch}`
8. Open MR creation URL from git output in browser

Example 2: Branch Naming Help

User: "What should I name my branch for issue 3456789?"

Skill response:
Use: `3456789-{brief-description}`

Examples:
- `3456789-fix-validation`
- `3456789-update-docs`
- `3456789-add-feature`

Create it with:
```bash
git checkout -b 3456789-your-description

**Example 3: Remote Setup Help**

User: "I created the issue fork, now what?"

Skill response: Add the issue fork as a remote:

git remote add {project}-{issue_number} [email protected]:issue/{project}-{issue_number}.git
git fetch {project}-{issue_number}

Replace {project} with your project name and {issue_number} with your issue number.

Then push your branch:

git push {project}-{issue_number} {your-branch-name}

## Resources

- [Drupal.org GitLab Guide](https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-drupal)
- [Creating Issue Forks](https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-drupal/creating-issue-forks)
- [git.drupalcode.org](https://git.drupalcode.org)