autograder-docs/gitflow.html at main · webtech-network/autograder-docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Autograder Gitflow Guide</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
      line-height: 1.6;
      color: #333;
      max-width: 960px;
      margin: 0 auto;
      padding: 20px;
    }

    h1,
    h2,
    h3 {
      border-bottom: 2px solid #eee;
      padding-bottom: 10px;
    }

    code, pre {
      background-color: #f6f8fa;
      border-radius: 3px;
      padding: 0.2em 0.4em;
      font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
      font-size: 85%;
    }

    pre {
      padding: 16px;
      overflow: auto;
    }

    .container {
      display: flex;
    }

    nav {
      width: 200px;
      padding-right: 30px;
      position: sticky;
      top: 20px;
      height: 100vh;
    }

    nav ul {
      list-style: none;
      padding: 0;
    }

    nav ul li a {
      text-decoration: none;
      color: #0366d6;
      display: block;
      padding: 5px 0;
    }

    nav ul li a:hover {
      text-decoration: underline;
    }

    main {
      flex: 1;
      width: 100%;
    }

    img {
        max-width: 100%;
        border: 1px solid #ddd;
        border-radius: 6px;
        padding: 8px;
        margin: 1em 0;
    }

  </style>
</head>

<body>
  <div class="container">
    <nav>
      <h3>Navigation</h3>
      <ul>
        <li><a href="./index.html">Main Docs</a></li>
        <li><a href="#introduction">Introduction</a></li>
        <li><a href="#branching-rules">Branching Rules</a></li>
        <li><a href="#protected-branches">Protected Branches</a></li>
        <li><a href="#standard-workflow">Standard Workflow</a></li>
        <li><a href="#hotfix-workflow">Urgent Hotfix</a></li>
        <li><a href="#chore-docs-workflow">Chore/Docs Workflow</a></li>
      </ul>
    </nav>
    <main>
      <header>
        <h1>📜 Autograder Gitflow Guide</h1>
      </header>

      <section id="introduction">
        <h2>1. Introduction</h2>
        <p>This document introduces the rules for branches and the most common workflows in the autograder project. </p>
      </section>
      <hr>
      <section id="branching-rules">
        <h2>2. Branch Naming Rules</h2>
        <p>First and foremost, it is imperative to understand branch naming rules.  A branch name is composed of two main parts: its classification and name, separated by a "/":</p>
        <pre><code>&lt;classification&gt;/&lt;name&gt;</code></pre>
        <p>A branch classification can be one of the following: </p>
        <ul>
          <li><strong>feature</strong>: Used for developing new features or significant additions to the codebase.  These changes introduce new functionality that didn't exist before. </li>
          <li><strong>fix</strong>: For resolving bugs or errors in existing code.  The goal is to correct something that's not working as intended without adding new features. </li>
          <li><strong>hotfix</strong>: Specifically for critical and urgent bug fixes that need to be deployed to production immediately.  These typically address issues impacting live users or system stability. </li>
          <li><strong>refactor</strong>: For restructuring existing code without changing its external behavior.  Refactoring aims to improve code readability, maintainability, or performance. </li>
          <li><strong>docs</strong>: Dedicated to changes related to documentation. </li>
          <li><strong>chore</strong>: Covers routine maintenance tasks and miscellaneous changes, like updating dependencies. </li>
          <li><strong>preset</strong>: Used for applying predefined grading configurations based on subjects. </li>
        </ul>
        <h3>Main and Development Branches</h3>
        <p>The <code>main</code> and <code>development</code> branches are special and do not follow the naming convention.  The <code>main</code> branch is considered the production branch.  Code should not be pushed directly to it; instead, it should first go to <code>development</code> for integration testing. </p>
      </section>
      <hr>
      <section id="protected-branches">
        <h2>3. Protected Branches & Code Review</h2>
        <p>To avoid sudden breaking changes, the <code>main</code>, <code>development</code>, and <code>preset/*</code> branches are protected.  All changes must be submitted via a pull request, which must be approved by at least one other person on the project.  The developer is responsible for requesting a review. </p>
        <p>It's the developer's responsibility to manually delete unused branches that are not part of a merged pull request. </p>
      </section>
      <hr>
      <section id="standard-workflow">
        <h2>4. Standard Development Workflow</h2>
        <p>Feature, fix, hotfix, and refactor branches should be merged into <code>development</code>.  After successful integration, a pull request should be created to merge <code>development</code> into <code>main</code>.  Once approved, the code becomes available for preset branches. </p>
        <img src="standard_workflow.png" alt="Standard Development Workflow Diagram">
      </section>
      <hr>
      <section id="hotfix-workflow">
        <h2>5. Urgent Hotfix Workflow</h2>
        <p>For critical bugs in production, it's permissible to create a pull request directly into <code>main</code> or a specific <code>preset/*</code> branch.  However, this should be a last resort; the standard workflow is always preferred to minimize risk. </p>
        <img src="hotfix_workflow.png" alt="Urgent Hotfix Workflow Diagram">
      </section>
      <hr>
      <section id="chore-docs-workflow">
        <h2>6. Chore and Docs Workflow</h2>
        <p>Changes to documentation (<code>docs/*</code>) can be merged directly into <code>main</code> as they pose no risk to the codebase. </p>
        <p>Chore branches, however, might cause dependency issues and should follow the standard development flow (merge to <code>development</code> first). </p>
        <img src="chore_docs_workflow.png" alt="Chore and Docs Workflow Diagram">
      </section>
    </main>
  </div>
</body>

</html>