Skip to content

Commit

Permalink
Merge pull request #9 from lukeoson/content/intro_to_pr
Browse files Browse the repository at this point in the history 
added content to intro_to_version_control.md for how to pull request
  • Loading branch information
@lukeoson
lukeoson authored Sep 22, 2024
2 parents 3d6f92a + 620dbf9 commit c16c5c6
Showing 1 changed file with 117 additions and 99 deletions.
216 changes: 117 additions & 99 deletions docs/Net-Auto/intro-to-version-control.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ tags:

## Coming Soon

This page is under construction. Please check back later for updates.
!!! bug "This page is under construction."
Please check back later for updates.


## Pull Requests
Expand All @@ -21,65 +22,74 @@ A workflow that uses feature branches and pull requests (PRs) is a sane way to m

### Understanding the Workflow

In this workflow:
**In this workflow:**

• Development happens in feature branches created from main.
- Development happens in feature branches created from main.

• Pull requests are opened to merge changes from branches into main.
- Pull requests are opened to merge changes from branches into main.

• Code review and testing occur before merging PRs.
- Code review and testing occur before merging PRs.

• GitHub Actions can be configured to run on PRs for continuous integration (CI).
- GitHub Actions can be configured to run on PRs for continuous integration (CI).

• Deployments happen when changes are merged into main.
- Deployments happen when changes are merged into main.

2. Setting Up Feature Branches
### Setting Up Feature Branches

Creating a New Branch
**Creating a New Branch**

1. Create a New Branch Locally
Create a New Branch Locally

```zsh
git checkout -b feature/my-new-feature
```
```zsh
git checkout -b feature/my-new-feature
```

- This command creates a new branch called feature/my-new-feature and switches to it.

- You can prefix your branch names with `feature/`, `bugfix/`, or `hotfix/` etc.

Make Your Changes

- Edit files, add content, and make any necessary changes in this branch.

Commit Your Changes

```zsh
git add .
git commit -m "Add new feature X"
```

### Push the Branch to GitHub Remote

```zsh
git push origin feature/my-new-feature
```

### Creating a Pull Request on GitHub

• This command creates a new branch called feature/my-new-feature and switches to it.
• It’s a good practice to prefix your branch names with feature/, bugfix/, or hotfix/ to indicate the purpose.
1. Navigate to Your Repository on GitHub

2. Make Your Changes
2. Create a Pull Request

• Edit files, add content, and make any necessary changes in this branch.
- GitHub usually detects that you’ve pushed a new branch and will prompt you to open a pull request.

3. Commit Your Changes
- Alternatively, you can go to the Pull requests tab and click New pull request.

```zsh
git add .
git commit -m "Add new feature X"
```
- Select your feature branch as the compare branch and main as the base branch.

4. Push the Branch to GitHub Remote
3. Fill Out PR Details

```zsh
git push origin feature/my-new-feature
```
- Title: Brief summary of the changes.

3. Creating a Pull Request on GitHub
- Description: Detailed explanation of what the PR does, any dependencies, or additional context.

1. Navigate to Your Repository on GitHub
2. Create a Pull Request
• GitHub usually detects that you’ve pushed a new branch and will prompt you to open a pull request.
• Alternatively, you can go to the Pull requests tab and click New pull request.
• Select your feature branch as the compare branch and main as the base branch.
3. Fill Out PR Details
• Title: Brief summary of the changes.
• Description: Detailed explanation of what the PR does, any dependencies, or additional context.
4. Submit the Pull Request
4. Submit the Pull Request

4. Adjusting GitHub Actions Workflow
### Adjusting GitHub Actions Workflow

To ensure your site builds correctly and passes any tests before merging, you can configure GitHub Actions to run on pull requests.

Modify Your GitHub Actions Workflow
**Modify Your GitHub Actions Workflow**

Update your .github/workflows/ci.yml file to trigger on pull requests as well as pushes.

Expand All @@ -97,132 +107,140 @@ on:
- main
```
• The pull_request event triggers the workflow when a PR targeting the main branch is opened, synchronized, or reopened.
• This allows your workflow to run CI checks on the changes in the PR before merging.
- The pull_request event triggers the workflow when a PR targeting the main branch is opened, synchronized, or reopened.
- This allows your workflow to run CI checks on the changes in the PR before merging.
Ensure your workflow has the appropriate permissions:
**Ensure your workflow has the appropriate permissions:**
```yaml
permissions:
contents: write
```
5. Workflow Steps for Pull Requests
### Workflow Steps for Pull Requests
Your existing workflow steps should largely remain the same. However, you might want to adjust the deployment step to prevent deployments from PRs.
Prevent Deployment on Pull Requests
**Prevent Deployment on Pull Requests**
You don’t want to deploy the site when the PR is created or updated, only after it’s merged into main. To achieve this, you can add a conditional to the deployment step.
You don’t want to deploy the site when the PR is created or updated, *only after it’s merged into main*. To achieve this, you can add a conditional to the deployment step.
Modify the Deployment Step:
```yaml
- name: Build and Deploy MkDocs Site
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
env:
GH_TOKEN: ${{ secrets.GH_TOKEN }}
run: |
mkdocs gh-deploy --force --clean
```
{% raw %}
```yaml
- name: Build and Deploy MkDocs Site
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
env:
GH_TOKEN: ${{ secrets. GH_TOKEN }}
run: |
mkdocs gh-deploy --force --clean
```
{% endraw %}
• if: github.event_name == 'push' && github.ref == 'refs/heads/main' ensures that the deployment step only runs when there’s a push to the main branch.
- `if: github.event_name == 'push' && github.ref == 'refs/heads/main'` ensures that the deployment step only runs when there’s a push to the main branch.

• This prevents deployments from occurring during PRs.
- This prevents deployments from occurring during PRs.

### Reviewing and Merging Pull Requests

Review the PR
**Review the PR**

- Automated Checks:
- GitHub Actions will run the workflow when the PR is opened or updated.
- You can check the Checks tab in the PR to see the status of the workflow.
- Ensure that all checks pass before merging.
- Code Review:
- Review the changes yourself or request a review from a collaborator.
- Look for correctness, style, and any potential issues.

• Automated Checks:
• GitHub Actions will run the workflow when the PR is opened or updated.
• You can check the Checks tab in the PR to see the status of the workflow.
• Ensure that all checks pass before merging.
• Code Review:
• Review the changes yourself or request a review from a collaborator.
• Look for correctness, style, and any potential issues.
**Merge the PR**

Merge the PR
**Ensure the PR is Up-to-Date**

1. Ensure the PR is Up-to-Date
• If there have been changes to main since you branched off, you might need to merge main into your feature branch or rebase.
- If there have been changes to main since you branched off, you might need to merge main into your feature branch or rebase.

```zsh
# Merge main into your feature branch
git checkout feature/my-new-feature
git fetch origin
git merge origin/main
```
```zsh
# Merge main into your feature branch
git checkout feature/my-new-feature
git fetch origin
git merge origin/main
```

- Resolve any merge conflicts if they arise.
- Push the updated branch to GitHub.

• Resolve any merge conflicts if they arise.
• Push the updated branch to GitHub.
**Merge the PR on GitHub**

2. Merge the PR on GitHub
• Click the Merge pull request button in the PR.
• Choose the merge method (e.g., Create a merge commit, Squash and merge, Rebase and merge).
• Confirm the merge.
- Click the Merge pull request button in the PR.
- Choose the merge method (e.g., Create a merge commit, Squash and merge, Rebase and merge).
- Confirm the merge.

3. Delete the Branch (Optional)
• After merging, you can delete the feature branch to keep your branch list clean.
• GitHub provides an option to delete the branch in the PR interface.
**Delete the Branch (Optional)**

7. Post-Merge Actions
- After merging, you can delete the feature branch to keep your branch list clean.
- GitHub provides an option to delete the branch in the PR interface.

GitHub Actions Deployment
### Post-Merge Actions

• Once the PR is merged into main, the GitHub Actions workflow will trigger again due to the push to main.
• The workflow will build and deploy your site as per the deployment step.
**GitHub Actions Deployment**

Monitor the Deployment
- Once the PR is merged into main, the GitHub Actions workflow will trigger again due to the push to main.
- The workflow will build and deploy your site as per the deployment step.

• Check the Actions tab to ensure the workflow runs successfully.
• Verify that your site is updated with the new changes.
**Monitor the Deployment**

8. Local Branch Management
- Check the Actions tab to ensure the workflow runs successfully.
- Verify that your site is updated with the new changes.

Update Your Local main Branch
**Local Branch Management**

After merging the PR, update your local main branch:
- Update Your Local main Branch

- After merging the PR, update your local main branch:

```zsh
git checkout main
git pull origin main
```

Delete Local Feature Branch (Optional)
**Delete Local Feature Branch (Optional)**

If you deleted the remote branch and want to delete your local feature branch:

```zsh
git branch -d feature/my-new-feature
```

9. Additional Tips
### Additional Tips

Branch Naming Conventions

• Use descriptive names for your branches to indicate their purpose.
• Examples: feature/user-authentication, bugfix/login-error, hotfix/critical-issue
- Use descriptive names for your branches to indicate their purpose.
- Examples: feature/user-authentication, bugfix/login-error, hotfix/critical-issue

Pull Request Templates

• You can create a PULL_REQUEST_TEMPLATE.md file in your repository to standardize PR descriptions.
- You can create a PULL_REQUEST_TEMPLATE.md file in your repository to standardize PR descriptions.

Code Owners and Reviews

• If collaborating with others, you can use GitHub’s CODEOWNERS file to automatically request reviews from specific people.
- If collaborating with others, you can use GitHub’s CODEOWNERS file to automatically request reviews from specific people.

Protected Branches

• Consider enabling branch protection rules on main to prevent direct pushes and enforce PR reviews and CI checks.
- Consider enabling branch protection rules on main to prevent direct pushes and enforce PR reviews and CI checks.

Continuous Integration and Testing

• Expand your GitHub Actions workflow to include tests, linting, and other checks to maintain code quality.
- Expand your GitHub Actions workflow to include tests, linting, and other checks to maintain code quality.

Documentation

• Update your project’s README or documentation to reflect your new workflow, so all contributors are aware.
- Update your project’s README or documentation to reflect your new workflow, so all contributors are aware.





Expand Down

0 comments on commit c16c5c6

Please sign in to comment.