Guides
v1.0
Guides
Start typing to search…
  1. Initiatives

Creating Initiatives

Learn how to create effective initiatives that generate high-quality code changes.

1. Describe the Change

Your description tells Tidra what to do.

Be specific:

❌ Too vague: "Update dependencies"

✅ Better: "Update the @company/shared-utils package from version 2.x to 3.x in package.json. Update import statements to use the new module structure."

Include context:

✅ "Add a SECURITY.md file to the root directory with our vulnerability disclosure policy. Use the template from [link]."

✅ "Update all GitHub Actions workflows to use Node 20. Change the node-version field in actions/setup-node from '16' to '20'."

Mention file locations:

✅ "Update the docker-compose.yml file in the root directory to use postgres:15 instead of postgres:13"

Show examples:

✅ "Replace calls to logger.log() with logger.info(). Example: logger.log('Starting service') becomes logger.info('Starting service')"

2. Select Repositories

Choose which repos should receive this change.

Manual selection:

  • Click checkboxes to select individual repos
  • Good for your first few initiatives
  • Full control over scope

Filter-based selection:

  • Use filters to automatically include repos
  • Examples: language, topics, has specific files
  • Good for larger initiatives

Tips:

  • Start small (5-10 repos) to validate quality
  • Expand to more repos after validating
  • Similar repos often work better (all Node.js, all Python, etc.)

Writing Effective Descriptions

Structure Your Description

1. What: What needs to change 2. Where: Which files or locations 3. Why (optional): Context that helps Tidra understand

Example:

What: Update the base Docker image to use Node 20
Where: In the Dockerfile, update the FROM line
Why: Node 16 is being deprecated and we need to migrate before the deadline

Change: FROM node:16-alpine to FROM node:20-alpine

Use Code Examples

Show before/after when helpful:

Update the GitHub Actions workflow:

Before:
- uses: actions/setup-node@v3
  with:
    node-version: '16'

After:
- uses: actions/setup-node@v4
  with:
    node-version: '20'

Specify Patterns

If the change follows a pattern:

Replace all instances of the old API endpoint:

Pattern: http://api.old.example.com/v1/* → https://api.new.example.com/v2/*

Also update the authentication header from X-API-Key to Authorization: Bearer

Handle Edge Cases

Mention exceptions or special handling:

Add a CODEOWNERS file with @platform-team as the default owner.

If a CODEOWNERS file already exists, add the default owner line only if it's not already present.

Common Mistakes to Avoid

Too Vague

❌ "Update configs" ✅ "Update the CI/CD config to use the new artifact storage location: s3://new-bucket/artifacts"

Multiple Unrelated Changes

❌ "Update Node version and also add linting and fix the README"

Do one thing per initiative. If you need multiple changes, create separate initiatives.

Assuming Knowledge

❌ "Use the new pattern"

Tidra doesn't know what "the new pattern" is. Be explicit.

Missing Critical Details

❌ "Update the Docker image"

Which image? Which version? Which file?

Advanced Techniques

Conditional Logic

Update the database connection string:

If the file is config/production.yaml, use: postgres://prod-db.example.com
If the file is config/staging.yaml, use: postgres://staging-db.example.com
Otherwise, use: postgres://localhost

Language-Specific Changes

For Python repos: Update requirements.txt to use pandas==2.0.0
For JavaScript repos: Update package.json to use @types/[email protected]
For Go repos: Update go.mod to require go 1.21

Referencing Documentation

Migrate the authentication flow to use OAuth 2.0 as described in our docs: [link]

Follow the migration guide for updating the client initialization and token refresh logic.

Refining and Regenerating

After reviewing generated changes, you might want to refine:

If changes are incorrect:

  1. Click Edit Description
  2. Add more detail or clarify
  3. Click Regenerate Changes
  4. Review again

If only some repos are wrong:

  1. Note the pattern in repos that failed
  2. Add specific guidance for those cases
  3. Regenerate

Example refinement:

Original: "Add error handling"

Refined: "Add try/catch blocks around all HTTP requests using the requests library. 
Log errors using logger.error() and return a 500 status code. 
Example: See error handling in services/payment/api.py"

Testing Your Description

Before generating across 100 repos:

  1. Select 3-5 representative repos
  2. Generate changes
  3. Review quality
  4. Refine description if needed
  5. Then scale to full scope

This saves time and ensures quality.

Templates and Examples

Config File Updates

Update [config file] in [location]:
- Change [field] from [old value] to [new value]
- Add new field [field name]: [value]
- Remove field [field name] if present

Code Refactoring

Replace [old pattern] with [new pattern]:

Old pattern:
[code example]

New pattern:
[code example]

Apply this to all files in [location].

Documentation

Add a new section to [file]:

Section title: [title]
Content: [what to include]
Location: [where in the file - after introduction, before examples, etc.]

Next Steps

Updated about 2 hours ago