Branch Organization

Purpose

Important to make sure the team is all in agreement on how the flow of changes will be applied. To ensure the team is on the same page, an agreed upon Git flow should be developed or selected.

This page describes Git Flow in delivery project following, which includes branch name, format, purpose and relative process.

Branch Type

Tên nhánh Tồn tại duy nhất? Mô tả Mục đích sử dụng
master Đúng Nhánh có tên master trong mỗi project Lưu trữ các bản release của project
develop Đúng Nhánh có tên develop trong mỗi project Lưu trữ code trong quá trình phát triển của dự án cho cả team
release-v<release_version_number> Không Các nhánh có tên bắt đầu bằng release Chuẩn bị cho các bản release sắp tới (change log, version...)
feature-us<user_story_number> hoặc features-us<user_story_number>-<short_description> Không Các nhánh có tên bắt đầu bằng features-us Lưu trữ code cho từng tính năng nhất định dựa theo mô tả của User Story
hotfix-<issue_id> hoặc
hotfix-<issue_id>-<short_description>
Không Các nhánh có tên bắt đầu bằng hotfix Lưu trữ code fix nhanh, cần release ngay và apply lên site nghiệm thu khách hàng, nhằm giảm thiểu tối đa downtime site khách
bugfix-<issue_id> hoặc
bugfix-<issue_id>-<short_description>
Không Các nhánh có tên bắt đầu bằng bugfix Lưu trữ code fix hoàn chỉnh cho bug phát sinh trên site khách hàng
collab-<short-description> Không Các nhánh có tên bắt đầu bằng collab Dùng cho feature/bugfix lớn cần sự hợp tác của nhiều người, với WIP dài từ 1-2 sprint
Các nhánh khác Không Các nhánh còn lại trong dự án, tùy theo từng mục đích sử dụng, tên nhánh chỉ cần tuân theo Quy định ở phần khai báo trong tài liệu này Tùy theo mục đích sử dụng cụ thể

Principles of Branch Name

Principle:

  • Tên nhánh được viết bằng tiếng anh, phân tách nhau bởi dấu gạch ngang.
  • Tên nhánh không dài quá 40 ký tự.

Name Principle of master and develop branch

  • master
  • develop

Name Principle of release branch

  • release-v<release_version_number>
  • Example:
    • release-v1.2.3, release-v3.0.0

Name Principle of features branch

  • features-us<user_story_number> or features-us<user_story_number>-<short_description>
    • <user_story_number> is defined User Story Number
    • <short_description> is short description about User Story, separate by -
  • Example
    • feature-us2.1.0, feature-us3.2-add-popup-checkout

Name Principle of hotfix branch

  • hotfix-<issue_id> or hotfix-<issue_id>-<short_description>
    • <issue_id> is id of issue in project, by view detail of issue to see issue_id in the url.
  • Example
    • Issue have url: https://gitlab.com/noodle_team/operations/-/issues/18, then the <issue_id> is 18. - Branch name is set to hotfix-18 or hotfix-18-cannot-complete-order-pos

Name Principle of bugfix branch

  • bugfix-<issue_id> or bugfix-<issue_id>-<short_description>
    • <issue_id> is id of issue in project, by view detail the issue to have issue_id in url.
  • Example:
    • Issue have url https://gitlab.com/noodle_team/operations/-/issues/18, then the <issue_id> is 18. Branch name is set to bugfix-18 or bugfix-18-cannot-complete-order-pos

Principles of Branch Creating

Branch master each project profile have only one 'master' branch. It is created on Create Project Profile Process, by implement Issue Template to create master.

Branches develop each project profile have only one 'develop' branch. It is created on Create Project Profile Process, by implement Issue Template on branch master.

Branches hotfix được tạo ra từ nhánh master, sau khi developer thực hiện xong việc hotfix sẽ tạo Merge Request đến nhánh master (để release) và tạo Merge Request tiếp theo đến nhánh develop (để bàn giao cho team develop) tránh conflict hoặc thiếu code trong các bản release tiếp theo

Branches bugfix được tạo ra từ nhánh develop, sau khi developer fix xong bug thì tạo Merge Request đến develop

Branches feature-us được tạo ra từ nhánh develop, sau khi developer fix xong bug thì tạo Merge Request đến develop

Branches release được tạo ra từ nhánh "develop", sau khi chuẩn bị metadata cho bản release thì tạo Merge Request đến nhánh master (để release), sau đó tạo thêm một Merge Request đến nhánh "develop" (để bàn giao cho team develop phần đã release).

Other Branches Không cần bản release ngay lập tức sau khi làm xong: Tạo ra từ nhánh develop, tên nhánh tuân thủ format trong phần Quy định ở tài liệu này.

Nếu cần bản release ngay lập tức sau khi làm xong: Tạo ra từ nhánh "master", tên nhánh phải bắt đầu bằng "hotfix", sau khi làm xong tạo Merge Request đến nhánh "master" trước rồi tạo Merge Request đến nhánh "develop".

Principles of Merge Request (MR)

Principle 1: Working on master and develop must via Merge Request (MR). Developer không push code trực tiếp lên 2 nhánh này mà rẽ nhánh ra và tạo MR đến 2 nhánh này tuỳ theo nhánh đó được rẽ ra từ đâu. Rẽ ra từ đâu thì Merge Request vào đó

  • Ví dụ: Nhánh feature-us1 rẽ ra từ nhánh develop sau khi developer hoàn thành công việc trên nhánh feature-us1 sẽ tạo MR vào nhánh develop

Principle 2: Những nhánh được tạo Merge Request đến nhánh master, phải có thêm 1 Merge Request nữa đến nhánh develop

  • Ví dụ 1: nhánh hotfix-1 được tạo ra từ master để hotfix cho site khách, sau khi Developer thực hiện xong việc hotfix sẽ tạo MR đến nhánh master trước để tạo release, sau đó tạo một MR đến nhánh develop để code tiếp tục đưa vào trong quá trình phát triển, không bị mất code trong lần release tiếp theo.
  • Ví dụ 2: Nhánh release-v1.2.1 được tạo ra từ nhánh develop, sau khi chuẩn bị các metadata để release xong thì sẽ tạo MR đến master để lưu trữ bản release, sau đó tạo MR đến nhánh develop để tiếp tục đưa vào quá trình phát triển.

Principles 3: Các MR đều phải có Milestone của tuần hiện tại.

  • Ví dụ:

Activity

Activity on master Branch

The idea is simple: there is one central repository. Each developer clones the repo, works locally on the code, makes a commit with changes, and push it to the central repository for other developers to pull and use in their work.

Create master Branch for new Project

  • Create only one master Branch for a new Project by creating Issue Template

Create master Branch for old Project

Edit master Branch

  • Never edit master Branch

Delete master Branch

  • Never delete master Branch

Activity on develop Branch

Create develop Branch

Notice: You must create master Branch first

  • Step 1: Go to project overview with url: https://gitlab.com/noodle_team/<project_name>

  • Step 2: choose branch "master", then click + button, then choose New branch

  • Step 3: Set Branch Name is develop, then click Create branch

Edit develop Branch

  • Never edit a develop Branch

Delete develop Branch

  • Never delete a develop Branch

Activity on feature Branch

Create feature Branch

To develop a feature of project, the developer need to create feature Branch and merge to develop branch after completing Notice: You must follow feature Branch Naming principle

Cách 1: Tạo feature branch và Merge Request cùng lúc

  1. Developer thưc hiện tạo branch feature như hình dưới

    1. Chọn source branch là develop
    2. Đặt tên branch là feature-<issue_id> hoặc feature-<issue_id>-<short_description> như hình dưới
    3. Bấm nút "Create Merge Request"


    Kết quả

  2. Developer Checkout branch ở IDE

    git fetch origin
    git checkout -b "<branch_name>" "<branch_name>"
    
  3. Developer thực hiện việc develop tính năng ở local và push lên nhánh feature

  4. Developer Sửa lại Merge Request sau khi đã hoàn thành feature

    1. Target branch là "develop" nếu không đúng thì sửa lại
    2. Title bỏ chữ WIP đi
    3. Điền thêm description mô tả những gì đã làm được
    4. Assignee tự assign Developer
    5. Milestone là milestone tuần hiện tại
    6. Check "Delete source branch when merge request is accepted." nếu chắc chắn đã hoàn thành User Story và không cần sử dụng nữa
  5. Developer Bấm nút "Save Change"

  6. Developer đợi pipeline Coding Standard chạy xong và báo success với tất cả các Job

  7. Developer bấm nút Merge

Cách 2: Tạo feature branch, sau khi làm xong feature mới tạo Merge Request.

Từ trang detail của từng project

  1. Developer truy cập Repository > Branches
  2. Developer bấm nút "New branch"
  3. Developer Tạo branch
    1. Create from chọn "develop"
    2. Branch name điền theo format ở tài liệu này.
    3. Bấm nút "Create branch"
  4. Developer Checkout branch ở IDE
    git fetch origin
    git checkout -b "<branch_name>" "<branch_name>"
    
  5. Developer sửa code ở local và push lên nhánh feature
  6. Developer sửa lại Merge Request
    1. Target branch là "develop" nếu không đúng thì sửa lại
    2. Title bỏ chữ WIP đi
    3. Điền thêm description mô tả những gì đã làm được
    4. Assignee tự assign Developer
    5. Milestone là milestone tuần hiện tại
    6. Check "Delete source branch when merge request is accepted." nếu chắc chắn đã hoàn thành User Story và không cần sử dụng nữa
  7. Developer Bấm nút "Save Change"
  8. Developer đợi pipeline Coding Standard chạy xong và báo success với tất cả các Job
  9. Developer bấm nút Merge

Edit feature Branch

  • Chỉ sửa tên branch feature khi branch chưa nằm trong Merge Request nào

Delete feature Branch

  • Xóa branch feature khi không nằm trong Merge Request nào và không có giá trị sử dụng. (Không bắt buộc)
  • Xoá branch feature sau khi đã Merge vào nhánh "develop" (không bắt buộc)

Activity on bugfix Branch

Notice: Khi có bug xuất hiện trên site nghiệm thu, do khách hàng thông báo hoặc developer tự phát hiện ra trong quá trình phát triển phần mềm.

  • Để khắc phục bug, Developer cần tạo Nhánh bugfix và được merge vào nhánh develop sau khi developer fix xong bug.

Create bugfix Branch

Cách 1: Tạo bugfix branch và Merge Request cùng lúc

  1. Developer thưc hiện tạo branch bugfix như hình dưới

    1. Chọn source branch là develop
    2. Đặt tên branch là bugfix-<issue_id> hoặc bugfix-<issue_id>-<short_description> như hình dưới
    3. Bấm nút "Create Merge Request"


    Kết quả

  2. Developer Checkout branch ở IDE

    git fetch origin
    git checkout -b "<branch_name>" "<branch_name>"
    
  3. Developer thực hiện việc fixbug ở local và push lên nhánh bugfix

  4. Developer Sửa lại Merge Request sau khi đã hoàn thành bugfix

    1. Target branch là "develop" nếu không đúng thì sửa lại
    2. Title bỏ chữ WIP đi
    3. Điền thêm description mô tả những gì đã được fix
    4. Assignee tự assign Developer
    5. Milestone là milestone tuần hiện tại
    6. Bỏ check "Delete source branch when merge request is accepted."
  5. Developer Bấm nút "Save Change"

  6. Developer đợi pipeline Coding Standard chạy xong và báo success với tất cả các Job

  7. Developer bấm nút Merge

Cách 2: Tạo bugfix branch, sau khi làm xong bugfix mới tạo Merge Request.

Từ trang detail của từng project

  1. Developer truy cập Repository > Branches
  2. Developer bấm nút "New branch"
  3. Developer Tạo branch
    1. Create from chọn "develop"
    2. Branch name điền "bugfix-<issue_id>-<issue_desription>"
    3. Bấm nút "Create branch"
  4. Developer Checkout branch ở IDE
    git fetch origin
    git checkout -b "<branch_name>" "<branch_name>"
    
  5. Developer sửa code ở local và push lên nhánh bugfix
  6. Developer sửa lại Merge Request
    1. Target branch là "develop" nếu không đúng thì sửa lại
    2. Title bỏ chữ WIP đi
    3. Điền thêm description mô tả những gì đã được fix
    4. Assignee tự assign là Developer
    5. Milestone là milestone tuần hiện tại
    6. Bỏ check "Delete source branch when merge request is accepted."
  7. Developer Bấm nút "Save Change"
  8. Developer đợi pipeline Coding Standard chạy xong và báo success với tất cả các Job
  9. Developer bấm nút Merge

Edit bugfix Branch

  • Chỉ sửa tên branch bugfix khi branch chưa nằm trong Merge Request nào

Delete bugfix Branch

  • Xóa branch bugfix khi không nằm trong Merge Request nào và không có giá trị sử dụng.

Activity on hotfix Branch

This branch is used to patch product after releasing. Merge to develop branch after completing

Create hotfix Branch

Notice: You must follow hotfix Branch Naming principle

Cách 1: Tạo hotfix branch và Merge Request cùng lúc

  1. Developer thưc hiện tạo branch hotfix như hình dưới

    1. Chọn source branch là master
    2. Đặt tên branch là hotfix-<issue_id> hoặc hotfix-<issue_id>-<short_description> như hình dưới
    3. Bấm nút "Create Merge Request"


    Kết quả

  2. Developer Checkout branch ở IDE

    git fetch origin
    git checkout -b "<branch_name>" "<branch_name>"
    
  3. Developer Tạo hotfix ở local và push lên nhánh hotfix

  4. Developer Sửa lại Merge Request sau khi đã hoàn thành hotfix

    1. Target branch là "master" nếu không đúng thì sửa lại
    2. Title bỏ chữ WIP đi
    3. Điền thêm description mô tả những gì đã được fix
    4. Assignee là Người quản trị hệ thống
    5. Milestone là milestone tuần hiện tại
    6. Bỏ check "Delete source branch when merge request is accepted."
  5. Developer Bấm nút "Save Change"

  6. Developer thông báo với Người quản trị hệ thống về hotfix cần release qua Slack cá nhân.

  7. Người quản trị hệ thống tạo release theo quy trình release hotfix.

  8. Người quản trị hệ thống thông báo lại với Developer sau khi release hoàn tất qua Slack cá nhân.

  9. Developer chuyển giao package hotfix cho khách hàng theo từng loại chuyển giao đã định nghĩa trong Wiki của Project.

Cách 2: Tạo hotfix branch, sau khi làm xong hotfix mới tạo Merge Request.

Từ trang detail của từng project

  1. Developer truy cập Repository > Branches

  2. Developer bấm nút "New branch"

  3. Developer Tạo branch

    1. Create from chọn "master"
    2. Branch name điền "hotfix-<issue_id>-<issue_desription>"
    3. Bấm nút "Create branch"
  4. Developer Checkout branch ở IDE

    git fetch origin
    git checkout -b "<branch_name>" "<branch_name>"
    
  5. Developer Tạo hotfix ở local và push lên nhánh hotfix

  6. Developer Sửa lại Merge Request

    1. Target branch là "master" nếu không đúng thì sửa lại
    2. Title bỏ chữ WIP đi
    3. Điền thêm description mô tả những gì đã được fix
    4. Assignee là Người quản trị hệ thống
    5. Milestone là milestone tuần hiện tại
    6. Bỏ check "Delete source branch when merge request is accepted."
  7. Developer Bấm nút "Save Change"

  8. Developer thông báo với Người quản trị hệ thống về hotfix cần release qua Slack cá nhân.

  9. Người quản trị hệ thống tạo release theo quy trình release hotfix.

  10. Người quản trị hệ thống thông báo lại với Developer sau khi release hoàn tất qua Slack cá nhân.

  11. Developer chuyển giao package hotfix cho khách hàng theo từng loại chuyển giao đã định nghĩa trong Wiki của Project.

Edit hotfix Branch

  • Chỉ sửa tên branch hotfix khi branch chưa nằm trong Merge Request nào

Delete hotfix Branch

  • Chỉ xóa branch hotfix khi đã release và đã được merge vào nhánh "develop"
  • Xóa branch hotfix khi không nằm trong Merge Request nào và không có giá trị sử dụng.

Activity on release Branch

Notice: While creating release package for the customer, create a release branch with:

  • Latest version of product
  • Have tag for latest version of product
  • release branch is Merge to develop branch
  • release branch is Merge to master branch

Create release Branch

Notice: You must follow release Branch Naming principle

  • Step 1: Người quản trị hệ thống xác định version cần phát hành dựa theo Version Naming Rules for Release.

  • Step 2: Người quản trị hệ thống tạo nhánh "release-v<version_number>" từ nhánh "develop"

    git checkout develop
    git fetch && git pull origin develop
    git checkout -b release-v<version_number>
    
  • Step 3: Người quản trị hệ thống thực hiện thay đổi version trong file Source/server/app/code/Magestore/Deli/etc/config.xml theo <version_number>


    Ví dụ: như hình bên dưới <version_number> là 1.1.0

  • Step 4: Người quản trị hệ thống thực hiện viết changelog cho release vào file CHANGELOG.md ở project root directory.

    v<version_number>
    =========
    
    #### Features Updated
    * [#<issue_id>](<issue_url>) -- <issue_title>
    #### Bug Fixed
    * [#<issue_id>](<issue_url>) -- <issue_title>
    
    

    Trong đó

    • <issue_id> là id của issue theo project tương ứng trên Gitlab
    • <issue_url> là url của issue trên Gitlab
    • <issue_title> là tiêu đề của issue


    Ví dụ

  • Step 5: Người quản trị hệ thống build lại code client và copy vào thư mục server

    cd Source/client/pos
    npm install
    npm run build
    cd ../../../
    rm Source/server/app/code/Magestore/Webpos/build
    mkdir -p Source/server/app/code/Magestore/Webpos/build/apps
    cp -r Source/client/pos/build Source/server/app/code/Magestore/Webpos/build/apps/pos
    
  • Step 6: Người quản trị hệ thống thêm file đã sửa vào git

    git add CHANGELOG.md Source/server/app/code/Magestore/Deli/* Source/server/app/code/Magestore/Webpos/build/*
    
  • Step 7: Người quản trị hệ thống thêm commit files

    git commit -m "release v<version_number>"
    
  • Step 8: Người quản trị hệ thống thêm tag

    git tag -a "v<version_number>" -m "release v<version_number>"
    
  • Step 9: Push branch và tag

    git push -u origin "release-v<version_number>" --tags
    
  • Step 10: Người quản trị hệ thống tạo Merge Request từ nhánh "release-v<version_number>" đến master. Điền các thông tin như sau

    1. Target branch là master
    2. Title là Release v<version_number>
    3. Description là không bắt buộc, có thể là change log hoặc để trống
    4. Milestone là milestone tuần tạo release.

Lưu ý: Không tick vào ô "Delete source branch when merge request is accepted."

  • Step 11: Người quản trị hệ thống bấm nút "Merge" để merge vào "master"

  • Step 12: Người quản trị hệ thống Tạo Merge Request đến nhánh "develop" tương tự như với "master"

  • Step 13: Người quản trị hệ thống bấm nút "Merge" để merge vào "develop"

Edit release Branch

  • Không sửa nhánh release

Delete release Branch

  • Không xóa nhánh release

Activity on other Branch

This is used to something related to project

Create other Branch

Cách 1: Tạo bugfix branch và Merge Request cùng lúc

  1. Developer thưc hiện tạo branch theo mục đích sử dụng từ nhánh "develop" với tên theo format ở phần quy định của tài liệu này.
  2. Developer Thực hiện sửa code ở local và push lên nhánh
  3. Developer tạo Merge Request đến nhánh "develop" với thông tin
    1. Target là nhánh "develop"
    2. Điền tiêu đề Merge Request
    3. Điền mô tả cho Merge Request
    4. Tự assign Developer
    5. Milestone là milestone tuần hiện tại
    6. Bỏ check "Delete source branch when merge request is accepted."
  4. Developer đợi pipeline Coding Standard chạy xong và báo success với tất cả các Job
  5. Developer bấm nút Merge

Edit other Branch

  • Chỉ sửa tên branch khi branch chưa nằm trong Merge Request nào

Delete other Branch

  • Xóa branch khi không nằm trong Merge Request nào hoặc không có giá trị sử dụng nữa.