Release is a pakaged build by delivery team. This bundle many features reflected from customer requirement. This Release Package will be deployed to the customer site.


Principles of version name

Principles: Follow SemVer

Khai báo

  • Khai báo trong module Magestore_Deli được implement vào trong bộ sản phẩm trước khi triển khai cho khách hàng, version khởi tạo là 1.0.0.

Princples Format

  • Trong đó:
    • <MAJOR> là số Phase customize.
    • <MINOR> là số lần cập nhật tính năng.
    • <PATCH> là số lần cập nhật bản vá lỗi.

Quy tắc tăng số

  • Mỗi lần release cập nhật vá lỗi số <PATCH> tăng lên 1 đơn vị.
  • Mỗi lần release cập nhật tính năng (có thể lẫn cả vá lỗi), số <MINOR> tăng lên 1 đơn vị.
  • Mỗi lần release cập nhật tính năng theo phase customize, số <MAJOR> tăng lên 1 đơn vị.
  • Khi tăng số <MINOR> số <PATCH> reset về 0
  • Khi tăng số <MAJOR> số <MINOR><PATCH> reset về 0


  • Version hiện tại là 1.0.0 nếu release chỉ bao gồm fixbug thì phiên bản tiếp theo là 1.0.1
  • Version hiện tại là 1.0.1 nếu release chỉ bao gồm tính năng (user story) thì phiên bản tiếp theo là 1.1.0
  • Version hiện tại là 1.1.0 nếu release bao gồm cả tính năng (user story) và fix bug thì phiên bản tiếp theo là 1.2.0
  • Version hiện tại là 1.2.0 nếu release có bao gồm tính năng của phase sau thì version tiếp theo là 2.0.0

Release package file structure


  • Compressed package: Currently supported *.tar.gz compress file extension.


  • Format: <project_path>-delivery-<tag_name>.tar.gz

    • <project_path>: path of project. Example: project has url "", <project_path> here is ""
    • <tag_name>: release tag of project, start with "v" character. Example: v1.0.0, v1.2.3

Package file's content

Title Description Is Required? Purpose
app/code/Magestore All files and directories under app/code/Magestore modules Yes Make sure all files deliver to customer alike all files we managing on our VCS
pub Some line, version of POS still store images in pub directory, release package have to have that folder to prevent missing image when deploy onto customer site Yes (if exist) Contains images use for some modules like: Webpos, Rewardpoints

Note: <tag_name> is release tag name
Store hashed content of all files in release package use sha1 algorithm Yes - To save the state of all file content that we deliver to customer
- To verify the file on customer site still in original content after a while usage (before we fixbug or deploy newer version).

Note: <tag_name> is release tag name
Store hashed content of file:var/.magestore_delivery/release-<tag_name>.manifest use sha1 algorithm Yes Quickly check the release manifest modified or not.


Internal Acceptance


  • All the issue cards has correct labels
  • All the issue cards need to release have to located in "State: Delivery Ready" column
  • All the code related issue card need to release have to merged into develop branch
  • All the team members join the Internal Acceptance
  1. Prepare environment (as same UAT site as posible - the site that we negotiate with customer when project start).
  2. Presenter comes to each issue anh plays follow the scenario described.
  3. Update issue label
    • Not qualified
      • Comment the reason not qualified
      • Move issue back to the column "State: Pending"
      • Notify to developer in charge with issue.
    • Qualified
      • Do not thing with issue.

Decide to do the release


  • All the issues need to release already done with Internal Acceptance
  1. Summary the result of all issues need to release

  2. Make decision

    If any issue with label "Type: Bug" or "Type: User story" does not meet its requirement or have to move back to previous state, that means the upcomming release is not qualified

    • Cancel (Not qualify the quality of code to deliver to the customer)

      • Plan next Internal Acceptance day.
    • Release (Qualified)

Release use tool

  1. From project page go to Repotitory > Branches. Type "release" in the search box, then press "Enter"

  2. If the branch named "release" exists click "Delete" button, otherwise go to step 4.

  3. Type "release" then click "Delete protected branch"

  4. Click button "New branch"

  5. Fill below information

    • Create from "develop"
    • Branch name "release"

    Then click "Create branch" button

  6. Waiting for release job running.

Prepare release manually

Prepare release manually


  • Have WebHooks Setting according to this guide
  • Issue Card type feature or bug need to release have to assign into the milestone of current week.
  • Issue card have to have at least two labels: "Type: Bug" or "Type: User story" and "State: Delivery Ready"
  1. Collect issue card need to release for project as requirement at prerequisite section above.

  2. Clone project to local computer

  3. Checkout branch develop

  4. From the collected issue list at step 1, choose the next version release follow [Principles of Naming Version]

  5. Create release branch from develop with name follow format: release-v<release_version>. <release_version> is the release number you selected at step 4

  6. Change release version

    Edit file Source/server/app/code/Magestore/Deli/etc/config.xml. Change the version to release version number

  7. Write release note

    Edit file (create new if not exists). Append the list issue card collect from step 1, write as below format

    ### Magestore <pos_line> <pos_version>
    ### Features:
    1. [#<issue_id>](<issue_url>): <issue_title>
    ### Bug fixed:
    1. [#<issue_id>](<issue_url>): <issue_title>
    • <release_version>: release version
    • <pos_line>: current POS line project using.
    • <pos_version>: current POS version project using.
    • <issue_id>: id of issue in project on gitlab
    • <issue_url>: url to view issue on gitlab
    • <issue_title>: issue title
  8. Build code client

  9. Copy build directory in Source/client/pos dir to pos dir in Source/server/app/code/Magestore/Webpos/build/apps

  10. Create release manifest

    Create a file contains all file content is hashed in sha1 algorithm

    • Delete all files under Source/server/var/.magestore_delivery/

    • Create release manifest file Source/server/var/.magestore_delivery/release-v<release_version>.manifest

    • Hash all file content under Source/server/app/code/Magestore

      Use command

      cd Source/server
      find app/code/Magestore -type f -exec sha1sum "{}" + >"var/.magestore_delivery/release-v<release_version>.manifest"
    • Hash file's content of release manifest file

      	sha1sum "var/.magestore_delivery/release-v<release_version>.manifest" >"var/.magestore_delivery/release-v<release_version>.manifest.sha1"
  11. Add change files to git

    git add Source/server/app/code/Magestore/Webpos/build Source/server/app/code/Magestore/Deli Source/server/var/.magestore_delivery
  12. Commit change files

    git commit -m "Release v<release_version>"
  13. Add release tag

    git tag -a "v<release_version>" -m "v<release_version>"
  14. Push commit and tag to remote

    git push -u origin release-v<release_version> --tags


Release manually


  1. Merge relase code to master branch

    git fetch
    git checkout -b master # omit -b flag if you already checkout master before
    git pull origin master
    git merge --no-ff relase-v<release_version> -m "Merge branch 'release-v<release_version>' into 'master'"
    git push -u origin master
  2. Merge release code back to develop branch

    git fetch
    git checkout -b develop # omit -b flag if you already checkout develop before
    git pull origin develop
    git merge --ff-only relase-v<release_version>
    git push -u origin develop
  3. Create release notes on gitlab

    • Access project tags page follow format:<project_path>/-/tags
    • Click edit to release tag
    • Copy release note from at youre root repository
    • Paste to release note section
    • Click button Save changes
  4. Move issue collected at step 1 of prepare release activity from column "State: Delivery Ready" to column "State: Delivery Done" in Group Issue Board.

  5. Create delivery issue

    • Create new issue on gitlab with title: "Delivery v<release_version> to customer"
    • Add labels: "Type: Task", "State: To Do" to the issue

Create release package

Create from tag

Create by hand

  1. Checkout release tag
    git checkout tags/v<release_version>
  2. Change to server dir
    cd Source/server
  3. Create release package
    # folder named "pub" is not exists
    tar -cvaf <project_path>-delivery-<tag_name>.tar.gz app/code/Magestore var/.magestore_delivery
    # folder named "pub" is exists
    tar -cvaf <project_path>-delivery-<tag_name>.tar.gz app/code/Magestore pub var/.magestore_delivery
    Note: The word inside "<" and ">" is variable, change it in some specific usage.

Use tool

Create from release full Source code package

Create by hand

  1. Download package from release page (note: only download package with extension .tar.gz)

    Downloaded package has below format: <project_path>-<tag_name>.tar.gz

  2. Extract downloaded package

    tar -xvf <project_path>-<tag_name>.tar.gz
  3. Change to server dir in extracted package

    cd <project_path>-<tag_name>/Source/server
  4. Create release package

    # folder named "pub" is not exists
    tar -cvaf <project_path>-delivery-<tag_name>.tar.gz app/code/Magestore var/.magestore_delivery
    # folder named "pub" is exists
    tar -cvaf <project_path>-delivery-<tag_name>.tar.gz app/code/Magestore pub var/.magestore_delivery

    Note: The word inside "<" and ">" is variable, change it in some specific usage.

Use tool

Update issue labels after release.

Update by hand

  1. Go to Gitlab Group issue board
  2. Drag issues related to the release from column "State: Delivery Ready" then drop to column "State: Delivery Done"

Use tool

  • Update soon

Create deployment issue card

Create by hand

  1. Go to Project detail page
  2. Create new issue card for Project
    • Title: "Delivery <release_tag>"
    • Description: Copy from release notes, then link back to project detail release page
    • Labels: "State: To Do", "Type: Deploy"
    • Milestone: Milestone of current week.

Use tool

  • Update soon.