Skip to content

Cacti_Contribution_Workflow_Guide.md

Latest commit

 

History

History
178 lines (120 loc) · 5.68 KB

Cacti_Contribution_Workflow_Guide.md

File metadata and controls

178 lines (120 loc) · 5.68 KB

Cacti Contribution Workflow Guide

The Git Aliases

These are stored in your ~/.gitconfig. They automate the heavy lifting of syncing and cleaning.

git sync (The Universal Sync)

This detects your current branch and updates it from the official Cacti repository.

git config --global alias.sync '!f() { \
    local branch=$(git rev-parse --abbrev-ref HEAD); \
    git fetch upstream && \
    git merge upstream/$branch && \
    git push origin $branch; \
}; f'

git gone (The Cleanup)

This identifies branches that have been merged and deleted on GitHub and removes them from your local machine.

git config --global alias.gone '!f() { \
    git fetch -p && \
    git branch -vv | awk "/: gone] / {print \$1}" | xargs -r git branch -d; \
}; f'

Helper Scripts

These scripts assist with bulk management across your /plugins directory.

Bulk Sync

Run this from your plugins/ directory to update every single plugin at once.

sync_all.sh

!#/bin/bash
find . -maxdepth 1 -mindepth 1 -type d -exec sh -c 'echo "Syncing {}..."; cd "{}" && git sync';

Contribution Workflow

Follow these steps every time you want to submit a change (like a typo fix).

Step 1: Pre-Flight

  1. Navigate to the plugin or core directory.
  2. Ensure you are on the main branch (e.g., git checkout develop or git checkout main).
  3. Run git sync to ensure your local and fork are identical to the official Cacti code.

Step 2: Create a Feature Branch

Never work directly on develop or main.

git checkout -b fix-typo-auth-logs

Step 3: Fix & Verify

  1. Run typos -w <filename> to fix errors.
  2. Review the changes with git diff.
  3. Run the Cacti-specific tests or linting if applicable.

Step 4: Commit & Push

  1. Stage: git add <filename>
  2. Commit: git commit -m "Brief description of fix"
  3. Push: git push origin fix-typo-auth-logs

Step 5: GitHub Actions

  1. Go to the official Cacti repository on GitHub.
  2. Click "Compare & pull request" on the yellow bar that appears.
  3. Verify the "base" is the official repo and the "head" is your fork's branch.
  4. Submit the PR.

Step 6: Post-Merge Cleanup

  1. Once merged, click "Delete branch" in the GitHub GUI.
  2. Back in your terminal: git checkout develop (or main).
  3. Run git sync (to get your own fix into your main branch).
  4. Run git gone (to delete the local feature branch).
    • *Note: If git gone fails because the IDs differ, use git branch -D <branch-name>.*

Quick Troubleshooting

  • "Upstream not found": Run git remote add upstream git@github.com:Cacti/<repo_name>.git.
  • "X11 forwarding failed": This is a harmless SSH warning; you can ignore it or use ssh -x to suppress it.
  • "Permission Denied (publickey)": Run ssh-add ~/.ssh/id_ecdsa to ensure your key is loaded into the agent.

Mass Fork

This script will use the GitHub CLI (gh) to automate the tedious process of finding, forking, and cloning every official Cacti plugin.

The mass-fork.sh Script

Create this file in your /plugins directory.

#!/bin/bash

# 1. Define the organization we are targeting
ORG="Cacti"
echo "Fetching list of all Cacti repositories..."
# 2. Get all repo names from the Cacti org that start with 'plugin_'
# We use --limit 300 to ensure we catch everything
REPOS=$(gh repo list $ORG --limit 300 --json name --jq '.[].name' | grep '^plugin_')
echo "Found $(echo "$REPOS" | wc -l) plugins."
# 3. Loop through and fork/clone
for REPO in $REPOS; do
    if [ -d "$REPO" ]; then
        echo "$REPO already exists locally, skipping..."
    else
        echo "Forking and cloning $REPO..."
        # --clone=true forks it to your account and downloads it
        # --remote=true sets up 'upstream' (Cacti) and 'origin' (You) automatically
        gh repo fork "$ORG/$REPO" --clone --remote
    fi
done
echo "All plugins are synced and ready"

How to use it

Make it executable:

chmod +x mass-fork.sh

Run it:

./mass-fork.sh

Automatic Remotes: Because of the --remote flag, you don't have to manually run git remote add upstream. Your git sync alias will work immediately on every single plugin this script downloads.

Duplicate Protection: It checks if the folder already exists (if [ -d "$REPO" ]) so you can run this script once a month to grab any new plugins the Cacti team has released without re-downloading everything.

Filtered: It specifically looks for the plugin_ prefix so you don't accidentally fork the main Cacti docs, website, or spine repositories into your plugins folder.

Super-Alias

Since you are managing a massive library now, you might want a way to see which plugins have uncommitted changes across your entire workspace. Run this to add a "status all" command:

git config --global alias.status-all '!f() { find . -maxdepth 2 -name ".git" -exec sh -c "echo \"\nChecking {}...\" && cd {}/.. && git status -s" \;; }; f'

(Now, typing git status-all from your plugins/ folder will give you a bird's-eye view of every plugin you're currently working on.)

Disable workflow actions

gh cache delete --all 
gh workflow list --json id -q '.[].id' | xargs -I {} gh workflow disable {}

If additional actions are added - run the above, or:

For example - "Nightly PHP Heavy Checks"

  • Go to your fork's Actions tab on GitHub.
  • In the left sidebar, click "Nightly PHP Heavy Checks".
  • Click the "..." (ellipsis) menu in the top-right of the workflow page.
  • Select "Disable workflow".

?

Loop for plugins directory:

find . -maxdepth 1 -mindepth 1 -type d -exec sh -c 'cd "{}" && echo "Checking {}..." && gh workflow list --json id -q ".[].id" | xargs -I {} gh workflow disable {}' \;