tfgrid_specs_and_feedback/process/contribute.md

# Contributing to TFGrid3

This document explains how to contribute to the TFGrid3 project through pull requests and code reviews. You can contribute either using Git commands or directly through the Gitea web interface.

## Understanding Pull Requests

Pull requests (PRs) are a way to suggest changes to the codebase. They allow contributors to:

1. Work on changes in isolation
2. Request feedback from maintainers and other contributors
3. Discuss potential modifications before they're integrated
4. Ensure quality through code review

## How to Contribute Changes

### Option 1: Contributing Through the Gitea Web Interface

If you're not familiar with Git commands or prefer a simpler approach, you can contribute directly through the Gitea web interface:

#### 1. Navigate to the File You Want to Edit

1. Browse to the repository on Gitea
2. Navigate to the file you want to modify
3. Click on the file to view its contents

#### 2. Edit the File

1. Click the "Edit" button (pencil icon) in the upper right corner of the file view
2. Make your changes in the text editor

#### 3. Propose Changes

1. Scroll down to the "Commit Changes" section
2. Enter a descriptive commit message explaining your changes
3. Select "Create a new branch for this commit and start a pull request"
4. Give your branch a descriptive name
5. Click "Propose Changes"

#### 4. Create Pull Request

1. On the next screen, add any additional details about your changes
2. Click "Create Pull Request"
3. Your changes will now be submitted for review

### Option 2: Using Git Commands

### 1. Fork the Repository (if you're not a team member)

If you don't have direct write access to the repository:

```bash
# Clone the repository to your local machine
git clone https://git.ourworld.tf/tfgrid/tfgrid3_feedback.git

# Add the original repository as a remote called "upstream"
git remote add upstream https://git.ourworld.tf/tfgrid/tfgrid3_feedback.git
```

### 2. Create a Branch

Always create a new branch for your changes:

```bash
# Make sure you're on the main branch and up-to-date
git checkout main
git pull origin main

# Create a new branch with a descriptive name
git checkout -b feature/your-feature-name
```

Use a descriptive branch name that reflects the changes you're making, such as:
- `feature/new-dashboard-widget`
- `fix/login-error`
- `docs/update-installation-guide`

### 3. Make Your Changes

Make the necessary changes to the codebase. Remember to:

- Follow the project's coding standards
- Write clear, concise commit messages
- Include tests if applicable
- Update documentation as needed

### 4. Commit Your Changes

```bash
# Add your changes
git add .

# Commit with a descriptive message
git commit -m "Add feature: brief description of what you did"
```

### 5. Push Your Branch

```bash
# Push your branch to the remote repository
git push origin feature/your-feature-name
```

### 6. Create a Pull Request

1. Navigate to the repository on Gitea
2. Click on "Pull Requests" and then "New Pull Request"
3. Select your branch as the source and main as the target
4. Fill in the PR template with:
   - A clear title
   - A detailed description of the changes
   - References to any related issues
   - Any additional information that might help reviewers

## The Review Process

### What Happens After You Submit a PR

1. **Automated Checks**: Depending on the repository configuration, your PR may trigger automated tests and checks.

2. **Code Review**: Maintainers and other contributors will review your code and may:
   - Suggest improvements
   - Ask questions about your implementation
   - Request changes before merging

3. **Addressing Feedback**: If changes are requested:
   - Make the necessary adjustments
   - Push additional commits to your branch
   - Respond to comments to explain your reasoning or confirm changes

4. **Approval and Merging**: Once your PR is approved:
   - A maintainer will merge your changes into the main branch
   - Your contribution will become part of the project

### Best Practices for Code Review

#### As a Contributor

- Be responsive to feedback
- Explain your reasoning when necessary
- Be open to alternative approaches
- Thank reviewers for their time and input

#### As a Reviewer

- Be respectful and constructive
- Focus on the code, not the person
- Explain why changes are needed, not just what needs to change
- Acknowledge good work and improvements

## After Your PR is Merged

- Your changes will be included in the next release
- You can delete your branch or keep it for reference
- Consider taking on new issues or helping review other PRs

## Need Help?

If you're new to Git, Gitea, or the pull request process, don't hesitate to ask for help. The community is here to support you in contributing to the project.

Thank you for contributing to TFGrid3!