|
1 | | -# Use of GitHub in GIRAF |
| 1 | +# GitHub Guide |
2 | 2 |
|
3 | | -This article explains how GitHub is used as a version control tool and more in the development of GIRAF applications. |
| 3 | +> **This page has moved.** See [Code Workflow](../Process/code_workflow.md) for the current Git and GitHub workflow documentation. |
4 | 4 |
|
5 | | -## Issues |
6 | | - |
7 | | -Issues are created by the development teams as well as the PO group. |
8 | | -An issue can be a bug report or a task creation request. |
9 | | - |
10 | | -The PO group prioritises, assigns and adds milestones to issues. |
11 | | - |
12 | | -The list of issues can be seen at each repository, by navigating to the "Issues" tab in the header of the repository. |
13 | | -Alternatively a [complete list](https://github.com/issues?q=is%3Aopen+is%3Aissue+archived%3Afalse+user%3Aaau-giraf) |
14 | | -for the whole organization can be viewed. |
15 | | -If the application has GitHub Projects set up, it is also possible to view the Issues by navigating to the [Projects](https://github.com/orgs/aau-giraf/projects/) tab. Here, issues can be assigned to sub teams and set up in Trello boards of readability. |
16 | | - |
17 | | -### Getting an Issue to Work on |
18 | | - |
19 | | -If you have time to work on a new issue, you can get a new one by following |
20 | | -these steps: |
21 | | - |
22 | | -1. Find an issue you want to work on |
23 | | -1. Ask the PO group if you can work on that issue |
24 | | - - The PO group might say no for various reasons and they have the final say, |
25 | | - as they have a better overview. |
26 | | - - There is usually a greater chance of getting a yes if the issue you've |
27 | | - picked is either _highest_ or _high_ priority. |
28 | | - |
29 | | -If you don't have a preferred issue you can ask the PO group to be assigned the |
30 | | -most pressing issue, as they have a good overview of the project and they will |
31 | | -most likely have some issues that they would like you to work with. |
32 | | - |
33 | | -### Creating an Issue |
34 | | - |
35 | | -If you find a bug, or have a task creation request you can create an issue: |
36 | | - |
37 | | -1. Go the the "Issues" tab of the relevant repository (E.g. <https://github.com/aau-giraf/foodplanner/issues>). |
38 | | -1. Press the green "New issue" button. |
39 | | -1. Choose whether to submit a bug report or task creation request, and press |
40 | | - "Get started". |
41 | | -1. Create a title and description for the issue. Please follow the template, and |
42 | | - don't delete the headers! |
43 | | - - The title for the *Task Creation Request* should tell what functionality |
44 | | - you would like added using the shown form "As a developer I would like the |
45 | | - docker config file to automatically update so that I don´t have to manually |
46 | | - update the config file". |
47 | | - Instead of the task being for the developer, guardian or user is also |
48 | | - frequently used. |
49 | | -1. Label the issue with appropriate labels. |
50 | | -1. It can be a good idea to inform the PO group when you are done, so they can |
51 | | - assign and refine the issue. |
52 | | - |
53 | | - |
54 | | -The same can be achieved by accessing the GitHub Projects (E.g. https://github.com/orgs/aau-giraf/projects/42) and adding the issue there. |
55 | | - |
56 | | -## Branches and Pull Requests |
57 | | - |
58 | | -We follow the [GitFlow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) |
59 | | -as explained in [the process manual of 2019](../Legacy/Handover/2019/process_group_information.md#our-adaptation-of-gitflow). |
60 | | - |
61 | | -During the sprints, all development is done in feature branches, branching out |
62 | | -from the `develop` branch. |
63 | | - |
64 | | - |
65 | | - |
66 | | -The **naming convention** for feature branches is `feature/xx` where `xx` is |
67 | | -replaced by the issue number. |
68 | | - |
69 | | -When the [Release Preparation](../Legacy/Handover/2020F/giraf_events.md#release-preparation) phase |
70 | | -begins, a release branch is created from the `develop` branch. |
71 | | -This branch is now used **instead** of `develop` until the sprint is over. |
72 | | - |
73 | | -The **naming convention** for release branches is `release/YYYYsXrZ` where `YYYY` |
74 | | -is replaced by year, `X` with the sprint number and `Z` with the release number. |
75 | | - |
76 | | -E.g. `release/2020s1r1` for 2020, sprint 1, release 1. |
77 | | - |
78 | | -### Creating a Branch |
79 | | - |
80 | | -#### During Sprints |
81 | | - |
82 | | -When you start working on an issue, you create a branch from `develop` called |
83 | | -`feature/xx` where `xx` is the issue number. |
84 | | - |
85 | | -From the terminal: |
86 | | - |
87 | | -```bash |
88 | | -git checkout develop |
89 | | -git checkout -b feature/xx |
90 | | -``` |
91 | | - |
92 | | -Or from GitHub: |
93 | | - |
94 | | -1. Make sure `develop` is selected. |
95 | | - |
96 | | -  |
97 | | - |
98 | | -1. Input the name of the branch (e.g. for feature 400). |
99 | | - |
100 | | -  |
101 | | - |
102 | | -1. Press "Create branch: feature/xx from 'develop'" |
103 | | - |
104 | | -#### During Release Preparation |
105 | | - |
106 | | -When you start working on a release fix, you create a branch from `release/*` |
107 | | -called `releasefix/xx` where `xx` is the issue number. |
108 | | - |
109 | | -```bash |
110 | | -git checkout release/* |
111 | | -git checkout -b releasefix/xx |
112 | | -``` |
113 | | - |
114 | | -Or from GitHub using the same procedure as above, **but** with the release |
115 | | -branch as base instead, and with the release fix naming convention. |
116 | | - |
117 | | -### Creating a Pull Request |
118 | | - |
119 | | -When you have finished your issue, it is time to create a pull request. |
120 | | -A pull request is a request to merge your branch into another branch. |
121 | | - |
122 | | -Before making the pull request, make sure that the code: |
123 | | - |
124 | | -- Only relates to a single issue. (One PR per user story) |
125 | | -- Is fully tested. |
126 | | -- Is reachable when opening the application. |
127 | | - |
128 | | -**Fully tested means that if any piece of the functionality is removed, a test |
129 | | -should fail.** |
130 | | - |
131 | | -**Creating a pull request on GitHub:** |
132 | | - |
133 | | -1. Open the "Pull requests" tab in the repository (e.g. <https://github.com/aau-giraf/foodplanner/pulls>) |
134 | | -1. Press "New pull request" |
135 | | -1. Select the appropriate branch as base. |
136 | | - - `develop` if during sprint |
137 | | - - `release/*` if during release preparation |
138 | | -1. Select your branch for as compare |
139 | | -1. Press "Create pull request" |
140 | | -1. Name the pull request `Feature xx` or `Feature xx: A title describing changes` |
141 | | -1. Write a description |
142 | | - - If you write `closes #xx` or `fixes #xx`, issue xx will be linked to the PR |
143 | | - and will close when the PR is merged. ([All keywords](https://help.github.com/en/enterprise/2.16/user/github/managing-your-work-on-github/closing-issues-using-keywords#about-issue-references)) |
144 | | - |
145 | | -## Code Review |
146 | | - |
147 | | -After being assigned a pull request, the group should review the code under the |
148 | | -_Files changed_ tab. Look for code that may be deprecated, unnecessary, |
149 | | -non-optimized or has weird formatting. |
150 | | - |
151 | | -Start at <https://github.com/aau-giraf/> |
152 | | - |
153 | | -1. Choose repository eg. weekplanner. |
154 | | -1. Click on the **Pull Request** tab. |
155 | | -1. Choose an open pull request from the list. |
156 | | -1. Click on the **Files Changed Tab**. All the changes can be seen in these files. |
157 | | -  |
158 | | - 1. Make a comment or suggestion on a single line or multiple lines by pressing |
159 | | - the blue + icon (move the cursor to a line). |
160 | | - The red square marks the selection icon which can be used to suggest code |
161 | | - that replaces the line(s). |
162 | | -  |
163 | | - You can view what the author will see by clicking **Preview**. |
164 | | -  |
165 | | -1. Having looked over all the files, click **Review changes**. |
166 | | - 1. If you made comments, make sure the author looks them through by choosing |
167 | | - **Request changes** before clicking **Submit review**. If changes are made, |
168 | | - you have to re-review the pull request! |
169 | | -  |
170 | | - 2. If the changes makes sense, click **Approve**. |
171 | | -  |
| 5 | +For historical GitHub practices from 2018-2020, see [Archive → Handover](../Archive/Handover/index.md). |
0 commit comments