Improve software engineering team communication with RFC

The Request for Comments (RFC) process is a method used to develop standards, protocols, and procedures, particularly in Internet technology and computer networking. It can also be adapted for the software engineering team to improve communication, decision-making, and documentation.

Here’s how we could apply it:

Proposal Initiation

Template for RFC:

## Author(s)
[Name(s) of the author(s)]
## Issue
[Brief description of the problem or opportunity]
## Proposal
[Detailed description of the proposed solution]
## Rationale
[Explanation of why this proposal is beneficial]
## Implementation
[Overview of how this would be implemented]
## Alternatives
[Other solutions considered and why they were not chosen]
## Impact
[Potential effects on existing systems, performance, etc.]
## Questions
[Open questions or areas needing further investigation]
## Timeline
[Proposed schedule for implementation]

Distribution and Review

Steps:

1. Create a dedicated space for RFCs (e.g., a GitHub repository or Confluence space)
2. Announce new RFCs in a central location (e.g., team chat, email list)
3. Set a standard review period (e.g., 2 weeks)
4. Assign a facilitator to manage the review process

Discussion

Steps:

1. Use a tool that allows inline comments (e.g., GitHub PR reviews, Confluence)
2. Encourage specific, actionable feedback
3. Hold a synchronous discussion session for complex RFCs
4. Document key points and decisions from discussions

Template for comments:

[Section]: [Comment]
[Suggested change, if any]
[Rationale for comment/change]

Revision

Steps:

1. The author addresses each comment, either by making changes or explaining why no change is needed
2. Update the RFC document with a change log
3. Notify reviewers of significant changes

Change log template:

## Change Log
- [Date]: [Brief description of change]
- [Date]: [Brief description of change]

Decision-making

Steps:

1. Define decision criteria (e.g., technical feasibility, alignment with goals, resource availability)
2. Establish a decision-making body (e.g., senior engineers, architects)
3. Hold a decision meeting or vote
4. Document the decision and rationale

Decision template:

## Decision
Status: [Accepted/Rejected/Needs Revision]
Date: [Decision Date]
Deciders: [Names or roles of decision-makers]

Rationale: [Explanation of the decision]
Next steps: [If accepted, immediate actions to be taken]

Implementation

Steps:

1. Create tasks or user stories based on the RFC
2. Assign an owner to oversee the implementation
3. Set up regular check-ins to track progress
4. Update the RFC with any significant deviations from the original plan

Implementation tracking template:

## Implementation Status
Start Date: [Date]
Target Completion: [Date]
Status: [In Progress/Completed/Delayed]

Milestones:
- [ ] [Milestone 1]
- [ ] [Milestone 2]
- [ ] [Milestone 3]

Notes:
[Any relevant notes on implementation progress or challenges]

Archiving

Steps:

1. Move completed RFCs to an “Implemented” or “Archived” section
2. Maintain an index of all RFCs for easy reference
3. Periodically review old RFCs for relevance or lessons learned

Archive-index template:

# RFC Archive
## Implemented
1. [RFC Title] - [Date] - [Link to RFC]
2. [RFC Title] - [Date] - [Link to RFC]
## Rejected
1. [RFC Title] - [Date] - [Link to RFC]
2. [RFC Title] - [Date] - [Link to RFC]
## Superseded
1. [RFC Title] - [Date] - [Link to RFC] - Superseded by: [Link to new RFC]
2. [RFC Title] - [Date] - [Link to RFC] - Superseded by: [Link to new RFC]

These templates and steps should provide a solid foundation for implementing an RFC process.

An example of a completed RFC file

TL;DR

# RFC: Implement Two-Factor Authentication

## Metadata
- RFC ID: AUTH-2FA-001
- Author: Jane Doe (jane.doe@company.com)
- Created: 2024-03-15
- Last Updated: 2024-04-01
- Status: Approved

## Change Log
- 2024-03-15: Initial draft
- 2024-03-22: Updated implementation details based on security team feedback
- 2024-03-28: Added cost estimate and timeline
- 2024-04-01: Final approval and minor edits

## Issue
Our web application currently relies solely on password-based authentication, which leaves user accounts vulnerable to unauthorized access if passwords are compromised.

## Proposal
Implement Two-Factor Authentication (2FA) as an optional security feature for all user accounts. This will add an additional layer of security by requiring users to provide two different authentication factors to verify their identity.

## Rationale
1. Enhanced Security: 2FA significantly reduces the risk of unauthorized access, even if a user's password is compromised.
2. User Trust: Offering 2FA demonstrates our commitment to protecting user data, potentially increasing user trust and satisfaction.
3. Industry Standard: 2FA is becoming an expected feature in many web applications, especially those handling sensitive information.

## Implementation
1. Authentication Methods:
   - Primary: Existing password-based authentication
   - Secondary: Time-based One-Time Password (TOTP) using a mobile authenticator app

2. User Flow:
   a. Users opt-in to 2FA through account settings
   b. Setup process guides users through installing an authenticator app and scanning a QR code
   c. Users verify setup by entering a generated TOTP
   d. On subsequent logins, users enter password followed by current TOTP

3. Technical Implementation:
   - Use the `pyotp` library for TOTP generation and verification
   - Store TOTP secret key securely in the user database (encrypted)
   - Implement rate limiting on 2FA attempts to prevent brute force attacks
   - Provide backup codes for account recovery in case of lost device

4. UI/UX Considerations:
   - Clear, step-by-step setup process with visual aids
   - Option to disable 2FA with appropriate warnings
   - Visual indicator in UI to show 2FA-enabled accounts

## Alternatives Considered
1. SMS-based 2FA: Rejected due to potential security vulnerabilities and increased operational costs.
2. Hardware security keys: Considered more secure but rejected due to higher barrier to entry for users.

## Impact
- Security: Significant improvement in account security
- Performance: Minimal impact; slight increase in login time for 2FA-enabled accounts
- User Experience: Minor added complexity during login, offset by improved security
- Backend: New database fields and API endpoints required

## Open Questions
1. Should 2FA be mandatory for admin accounts?
2. What is the process for helping users who lose access to their authenticator device?

## Cost Estimate
- Development: 3 developer weeks
- QA: 1 week
- Design: 3 days
- Ongoing: Minimal (customer support for account recovery)

## Timeline
- Week 1-2: Backend implementation
- Week 3: Frontend implementation
- Week 4: Testing and QA
- Week 5: Beta testing with select users
- Week 6: Full rollout

## Decision
Status: Approved
Date: 2024-04-01
Deciders: Senior Engineering Team, Security Lead

Rationale: The proposal aligns with our security goals and industry best practices. The implementation plan is thorough and addresses potential issues. The benefits to user security outweigh the minor added complexity.

Next steps:
1. Create project in JIRA and break down into tasks
2. Assign team members to begin implementation
3. Schedule check-in for end of Week 2 to ensure project is on track