Comments & Collaboration

This guide covers everything you need to know about using comments in Gira for team collaboration, progress tracking, and maintaining detailed ticket history.

Overview

Comments in Gira provide asynchronous collaboration capabilities that help teams communicate about specific tickets, track progress, and maintain detailed audit trails. Each comment is stored with the ticket and includes author information, timestamps, and full content history.

Understanding Comments

What are Comments?

Comments in Gira are: - Structured notes attached to specific tickets - Timestamped entries that create an audit trail - Collaboration tools for team communication - Progress tracking mechanisms for detailed updates - AI-friendly with support for automated commenting

Comment Structure

Each comment contains: - Unique ID: UUID for precise reference - Author: Person or system that created the comment - Timestamp: When the comment was created (ISO 8601 format) - Content: The actual comment text - Edit History: Track if and when comments are modified

Use Cases for Comments

1. Progress Updates: Document work status and developments
2. Technical Notes: Record implementation decisions and challenges
3. Collaboration: Communicate with team members about ticket details
4. Questions & Answers: Clarify requirements or discuss solutions
5. AI Integration: Automated progress tracking and decision logging

Adding Comments

Basic Comment Creation

Add a simple comment to a ticket:

gira comment add GCM-123 --content "Started working on the authentication feature"

This creates a comment with: - Auto-generated unique ID - Current timestamp - Your Git user as the author - The specified content

Interactive Comment Creation

Add a comment using an interactive editor:

gira comment add GCM-123 --editor

This opens your default editor for writing longer, multi-line comments with formatting.

Comment Creation Options

• --content "..." - Specify comment text directly
• --content-file FILE - Read comment content from a file
• --editor - Open editor for multi-line comments
• --attach FILE - Attach file(s) to the comment (can be used multiple times)

Best Practices for Adding Comments

1. Be Descriptive: Include enough context for others to understand
2. Regular Updates: Comment on significant progress or blockers
3. Technical Details: Document important implementation decisions
4. Consistent Format: Use similar structure for similar types of updates

Viewing Comments

List All Comments

View all comments for a ticket:

gira comment list GCM-123

This displays: - Comment ID for reference - Author name - Creation timestamp - Full comment content - Edit indicators if applicable

Filtered Comment Views

Show only recent comments:

gira comment list GCM-123 --limit 5

Show comments with detailed information:

gira comment list GCM-123 --verbose

Reverse chronological order (oldest first):

gira comment list GCM-123 --reverse

Comment List Options

• --limit N - Show only the N most recent comments
• --reverse - Show oldest comments first
• --format - Output format: table, json, yaml, csv, tsv, text, ids
• --verbose - Show detailed information including attachment details
• --fields - Comma-separated list of fields for JSON output
• --filter-json - JSONPath expression to filter JSON output

Managing Comments

Deleting Comments

Remove a comment permanently:

gira comment delete GCM-123 COMMENT-ID

Skip confirmation prompt:

gira comment delete GCM-123 COMMENT-ID --force

Delete Comment Options

• --force - Skip confirmation prompt

Note: Comments are permanently deleted and cannot be restored. The comment ID can be found using gira comment list GCM-123.

Comment Workflows

Progress Tracking Workflow

Document work progress systematically:

# Start work comment
gira comment add GCM-123 --content "Started implementation of user authentication system"

# Progress update
gira comment add GCM-123 --content "Completed OAuth integration, now working on session management"

# Completion comment
gira comment add GCM-123 --content "Implementation complete, ready for testing"

Technical Documentation Workflow

Record technical decisions and challenges:

# Implementation decision
gira comment add GCM-123 --content "
Decided to use JWT tokens for session management because:
- Stateless architecture requirements
- Better scalability for microservices
- Built-in expiration handling
"

# Challenge and solution
gira comment add GCM-123 --content "
Encountered CORS issues with authentication endpoints.
Solution: Added proper Access-Control headers in middleware.
See commit abc123 for implementation details.
"

Collaboration Workflow

Facilitate team communication:

# Question for team
gira comment add GCM-123 --content "@alice Can you review the API design before I implement the frontend integration?"

# Review feedback (alice adds this comment herself)
gira comment add GCM-123 --content "API looks good, suggest adding rate limiting to the login endpoint"

# Response and action
gira comment add GCM-123 --content "Good point @alice, added rate limiting. Ready for frontend work."

Advanced Comment Features

Multi-line Comments

For longer comments, use the editor:

gira comment add GCM-123 --editor

This allows you to write detailed comments with: - Multiple paragraphs - Code snippets - Formatted lists - Technical explanations

AI and Automated Comments

For AI agents and automated systems, use descriptive prefixes in content:

# AI progress comment
gira comment add GCM-123 --content "[AI] Automated analysis complete:
- Code coverage: 95%
- Performance tests: All passing
- Security scan: No issues found
Ready for human review."

# System status comment
gira comment add GCM-123 --content "[CI/CD] Build #456 completed successfully:
- Unit tests: 123/123 passed
- Integration tests: 45/45 passed
- Deployment: Staging environment updated"

Comment Templates

Create consistent comment structures:

# Daily standup update template
gira comment add GCM-123 --content "
## Today's Progress
- Completed user authentication logic
- Fixed OAuth callback handling

## Next Steps
- Implement password reset functionality
- Add integration tests

## Blockers
- Waiting for API key from external service
"

Integration with Development Workflow

Git Integration

Reference commits and branches in comments:

gira comment add GCM-123 --content "
Implemented core authentication in commit a1b2c3d
Created feature branch: feature/user-auth
Next: Add unit tests and documentation
"

Pull Request Integration

Link comments to code reviews:

gira comment add GCM-123 --content "
Created PR #456 for review
- Added comprehensive unit tests
- Updated documentation
- Addressed security considerations
Please review authentication flow implementation
"

Issue Tracking

Document bugs and solutions:

gira comment add GCM-123 --content "
Found issue with session timeout handling:
- Sessions expire too quickly in development
- Fixed by adding environment-specific config
- Testing in staging before production deploy
"

Team Collaboration Patterns

Code Review Comments

Structure code review feedback:

# Review request
gira comment add GCM-123 --content "
Ready for code review:
- Authentication logic complete
- Unit tests at 95% coverage
- Documentation updated
Please focus on security aspects and error handling
"

# Review feedback (reviewer adds this comment)
gira comment add GCM-123 --content "Code review feedback:
✅ Security implementation looks solid
✅ Error handling is comprehensive
⚠️ Consider adding integration tests for OAuth flow
✅ Documentation is clear and complete
Approved with minor suggestions"

Standups and Status Updates

Daily progress reporting:

gira comment add GCM-123 --content "
## Standup Update - 2025-07-15
**Yesterday:** Completed OAuth integration
**Today:** Working on session management and testing
**Blockers:** Need staging environment access for integration tests
**ETA:** Feature complete by end of week
"

Planning and Estimation

Document planning decisions:

gira comment add GCM-123 --content "
Planning session notes:
- Estimated 5 story points for this feature
- Breaking into 3 subtasks: auth, sessions, tests
- Dependencies: API gateway configuration
- Risk: External OAuth provider rate limits
"

Best Practices

Comment Quality

1. Clear Context: Always include enough background information
2. Actionable Items: Highlight what needs to be done next
3. Technical Details: Document important implementation choices
4. Timing Information: Include relevant dates and deadlines

Team Communication

1. @mentions: Reference team members when input is needed
2. Status Updates: Regular progress communication
3. Decision Documentation: Record why choices were made
4. Issue Resolution: Document how problems were solved

Maintenance

1. Regular Updates: Keep comments current with actual progress
2. Additional Comments: Add new comments when situations change (editing is not available)
3. Delete Outdated Comments: Remove outdated information using gira comment delete
4. Consistent Format: Use similar structures for similar updates

Comment Organization

Comment Categories

Organize comments by type:

Progress Comments:

gira comment add GCM-123 --content "[PROGRESS] Completed authentication module testing"

Technical Comments:

gira comment add GCM-123 --content "[TECH] Decided to use Redis for session storage due to performance requirements"

Blocking Comments:

gira comment add GCM-123 --content "[BLOCKED] Waiting for API documentation from external team"

Comment History

Track comment evolution:

# View all comments to see progression
gira comment list GCM-123

# Filter to see only recent updates
gira comment list GCM-123 --limit 10

# Use JSONPath filtering to find comments by specific author
gira comment list GCM-123 --format json --filter-json '$[?(@.author=="alice@example.com")]'

Troubleshooting

Common Issues

Comments not showing properly - Verify ticket ID exists: gira ticket show GCM-123 - Check comment formatting and special characters - Ensure proper permissions for ticket access

Cannot delete comments - Verify comment ID is correct: gira comment list GCM-123 - Check that comment exists and isn't already deleted - Use the correct syntax: gira comment delete GCM-123 COMMENT-ID

Author attribution issues - Comments are attributed to the current Git user automatically - Check Git configuration: git config user.name and git config user.email - Use content prefixes like [AI] or [System] to indicate automated comments

Performance with Many Comments

For tickets with extensive comment history: - Use --limit to view recent comments only - Use --filter-json with JSONPath expressions to find specific discussions - Consider archiving old tickets with extensive history - Use JSON output for programmatic processing

Comment Formatting

Handle special characters and formatting:

# Use quotes for content with special characters
gira comment add GCM-123 --content "Fixed issue with & character in URLs"

# Use editor for complex formatting
gira comment add GCM-123 --editor
# Then write formatted content in the editor

See Also

• Ticket Management - Creating and managing tickets
• Sprint Management - Time-boxed development cycles
• Epic Management - Large initiative organization
• CLI Reference - Complete command reference