CUBRID uses JIRA to manage its projects, and all changes are managed on an issue-by-issue basis. JIRA issues can have nine statuses as shown in the diagram: Open, Confirmed, Analysis, Develop, Handover, Backport, Resolved, Test, and Closed, and the status of an issue is updated according to its progress. An issue starts in the Open status and is completed when it reaches Closed.

The primary actor responsible for advancing an issue may vary depending on the status.

For instance, in Open status, the project maintainer performs a triage on the issue, approves it, and assigns it to a developer, moving it to Confirmed status.

Analysis status involves the developer analyzing the assigned issue, including analysis, design, proof of concept (POC), and peer review of the design before development begins.

Develop status involves developing based on the analyzed information, peer reviews, unit testing, and code merging.

Handover status is a preparatory stage for transferring to the Quality Assurance (QA) team, including organizing test scenarios, writing manuals, and modifying regression tests.

In Resolved status, the QA maintainer assigns the issue to a tester.

The designated tester then changes the status to Test and performs QA tasks.

Backport status reflects the tested issue's code and manual to a lower version.

However, the project maintainer can make modifications such as content and status transitions at any stage.

CUBRID is an open source project that operates on the basis of a general open source project development process. The developers of CUBRID contribute to one big project called CUBRID by using collaboration tools for open source development projects.

The purpose of this document is to describe the development workflow using collaborative tools and to establish the basic principles for mutual consensus on a development culture. This document can be flexibly applied according to the situation and modify/develop through mutual agreement:

• Individuals and interactions over processes and tools

• Working software over comprehensive documentation

• Responding to change over following a plan

The CUBRID development process is based on the following two tools:

• Issue Tracking: JIRA (jira.cubrid.org)

• Code Repository and Code Review: GitHub (github.com/CUBRID)

All CUBRID projects, feature additions, and bug fixes start with the creation of JIRA issues. In accordance with JIRA's Issue workflow, contributors will begin designing and implementing their problem after defining and investigating it. In the design and implementation stage, the code is merged in CUBRID after the review through branch creation, Pull Request, and code review on Github. CUBRID is developed sustainably by repeating the above process.

The project maintainer changes the status from Open to Confirmed through the Triage process. At this point, the following fields are specified:

• assignee: developer in charge of the issue

• planned version/s: the version/s in which the issue is planned to be addressed

• priority: set based on the importance of the issue

• triage: always set to 'Approved' when transitioning to the Confirmed status

• labels: Freely set the labels as you need

QA maintainers and test handler can revert an issue from the Resolved status to Confirmed status by pressing the "QA Not Satisfied" button if the issue fails the QA test, or a specification change is needed.

The assignee of the issue can revert an issue from Analysis or Develop status to Confirmed status by pressing the "stop work" button if the issue can no longer proceed due to other tasks.

After completing the implementation (peer review and code merge), the responsible developer presses the "Accept the fix" button to transition the work to the Handover status, preparing it for transfer to the Quality Assurance (QA) team. In the Handover status, tasks such as writing manuals, creating test items, and updating regression test cases due to specification changes are performed.

Once transferred to the Quality Assurance team, if the QA maintainer or test handler has additional requests related to testing, they can press the "Need Something" button to revert to the Handover status.

The entire development process contains the workflows of JIRA, Github, and post-merge (QA Testing) situations. The purpose of this document is to explain each process detailedly. It is recommended to read the entire document before starting to contribute to the CUBRID project. As you go through the development process, it is recommended to refer to the guides in that section for each step in the process.

The QA assignee can press the "Start Test" button, which changes the status to Test. The Test status involves manual testing, writing test scenarios, and verifying the success of these tests.

Project maintainer, QA maintainer, and QA assignee can revert the status of a concluded issue (Closed) back to Test using the "Need Test" button if additional testing is deemed necessary.

The Assignee, who is a developer designated through the Triage process, can initiate the task by pressing the "Start Analysis" or "Start Develop" button, setting a due date, and subsequently updating the issue's status to Analysis or Develop. Note that the assignee can be reassigned as needed.

The Analysis state consists of analysis (including debugging), Proof of Concept (POC), design, and design review.

The Develop state involves implementation, unit testing, and peer review.

The Assignee must change the development status according to the ongoing development phase.

After completing the tests, the QA assignee (the tester in charge) presses the "Need Backport" button to request a backport to the lower versions specified in the planned version. The Backport status involves conducting backporting activities for the code and test cases to branches other than develop branch specified in the planned version.

When the QA assignee completes the necessary QA tasks for an issue, the issue is concluded and the status is changed to Closed subsequently. During this procedure, the following checks are made:

• QA Scenario Addition/Modification and Verification

• Backport Reflection According to Planned Version/s

Acknowledgments

Git branch is a useful tool that allows multiple developers to work on multiple tasks at the same time on one piece of software for multiple purposes. For more detail, please refer to the link.

Most of the Github projects have serveral branches set for the purpose. For example, the develop branch keeps the latest developments, and the master (or main) branch manages the stable versions. There are several ways to run an open source project by leveraging each branch in a purposeful way. CUBRID is operated based on the Vincent Drissen branch model which has been applied by many open source projects.

CUBRID's Branch Model VS. VD Branch Model

In the Vincent Drissen model (hereinafter referred to as the VD model), there are permanently maintained branches such as develop, master, and temporary branches such as release, feature, and hotfix. The difference between the CUBRID branch model and the VD model is that in the CUBRID branch model, we maintain the released version's branch permanently, (e.g. release/10.2, release/11.0). For example, even if the develop branch is on the latest version 12, the release/10.2 is also maintained for minor version upgrade releases 10.2.2, 10.2.3, 10.2.4...

In the VD model, a pre-release branch is created and it performs the same role as the release branch which is temporarily created during the release of the latest version. For more details, please see the Release Section.

For issues that are difficult to complete with one Pull Request, you can utilize a feature branch. Feature branches are described in a separate section that follows.

In the case of developing new features and fix bugs, you can ask the CUBRID committers to create a feature branch in the develop branch.

Create the name of the Feature Branch as follows:

• feature/<name>

example) feature/javasp, feature/tde, feature/truncate_table

• If you set the name as above, The Github Checks can be performed automatically.

The main purpose of the feature branch is to divide the code review into several rounds when the size of the code to be merged is large. Rather than merging only a part of the function in the develop branch, the feature branch will conduct efficient code review with multiple PRs and merge them more reliably in the develop branch.

Note that git commands are managed as follows:

# 1. create feature branch 
git remote add upstream 
http://github.com/cubrid/cubrid

git fetch upstream
git checkout -b feature/my_feature upstream/develop
git push -u upstream feature/my_feature

# 2. Multiple PRs on github
git fetch upstream
git checkout -b CBRD-OOOOO upstream/feature/my_feature
   # many commits (development in progress)
git push -u origin CBRD-OOOOO
   # Code review after PR creation
# 2. Repeat multiple times == multiple review rounds

# 3. sync with develop by merge (do not PR commit for sync)
git checkout feature/my_feature
git fetch upstream
git merge upstream/feature/my_feature // should be fast-forward merging
git merge upstream/develop
git push upstream feature/my_feature

# 2. Repeat multiple times == multiple review rounds

git push origin CBRD-OOOOO

# Create PR for CBRD-00000

*Note: Feature branches can be created at any time, and will be deleted after the feature has been reviewed and merged into the develop branch.

It's easy to understand that Git works only on branches, regardless of the repository. So, contributors do not have to do the sync between the main repository of CUBRID and their own forked repository.

Before proceeding with development, you only need to get a branch from upstream, start work. When you want to merge your work on the upstream (main) repository after some commits, you push the changes to your origin (forked) repository.

After pushing your changes on your origin (forked) repository, you can make a Pull Request.

You can refer to the following script:

git remote add upstream https://github.com/CUBRID/cubrid.git

git remote -v
#====
#    origin  http://github.com/hgryoo/cubrid (fetch)
#    origin  http://github.com/hgryoo/cubrid (push)
#    upstream        http://github.com/cubrid/cubrid (fetch)
#    upstream        http://github.com/cubrid/cubrid (push)

git fetch upstream

# Get a new branch to work on, create a branch from upstream!
# To prevent being reflected incorrectly by git push
# The two commands below must always be executed together.
git checkout -b CBRD-55555_my_work upstream/develop
git push -u origin CBRD-55555_my_work

# Add and commit your changes during your work
git add src/you/code
git commit -m 'code change'

# NOTE: Always write the remote name and branch name to prevent 
#       uploading to wrong remote
# Push your changes to your remote repository 
git push origin CBRD-55555_my_work

# When you want to get and sync with upstream's change
git fetch upstream
git merge upstream/develop

After completing the tasks ("HANDOVER", "BACKPORT"), the Assignee presses the "Check-in Fix" button to change the status to "RESOLVED" and transfers the issue to the QA maintainer. After the transfer to QA, the developer and QA handler communicate through issue comments.

When changing to the "RESOLVED" status, the following fields must be completed:

• QA assignee: Automatically assigned, no changes needed. (Default: QA maintainer)

• Resolution: "Done"

• manual: Indicates whether manual creation or modification is required. (need manual)

• QA scenario

  • not required: No additional QA scenario needed (default)

  • required: Additional QA scenario needed

  • revise required: Modifications needed for an existing QA scenario

• Fix version/s: Specifies the version in which the issue was merged (this field is referenced by the QA team for testing and release).

The QA maintainer assigns a QA assignee. If the QA assignee can no longer test the issue due to other tasks, they can press "Stop Test" button to change the status back to "RESOLVED".

The project maintainer can change the status to "RESOLVED" by pressing the "Bug Invalid" button if an issue screened as "OPEN" is determined not to be a bug. Similarly, if the Assignee (the developer in change) determines during the issue progression ("CONFIRMED", "ANALYSIS", or "DEVELOP") that no changes are necessary, they can press the "Resolve without fix" button to change the status to "RESOLVED". Subsequently, the QA maintainer can either change the status to "CLOSED" to conclude the issue or reassess and revert it to "OPEN" if it is deemed as a bug.

The QA team uses a CI tool called Jenkins to run the test system. When the Pull Request is merged, Jenkins is connected to Github and automatically tests the merged commit. (Reference: )

All tests are performed in Jenkins, and the result report is available at . On the left side of the page, you can see the test result report by version and a summary of the latest test report is displayed on the right side.

If you click the test result report on the left, there is a tab as shown in the figure below. Each shows the results of testing for function, performance, and memory leaks. (The button on the first right 'verify status' is not used by the development team).

The test is divided into a functional test and a non-function test. In terms of the functional tests, we are conducting tests for Linux and Windows environments respectively. Windows currently test fewer items than Linux.

A backport is to bring the features and fixes of a new version to a previous version. For example, if a bug which is found and fixed in CUBRID latest version, also occurs in CUBRID 10.2.1 and needs to be fixed, then backporting is performed.

In this case, from the Github tool's point of view, the commit which is merged in the develop branch is merged bacak to the release/10.2 branch. Note that in the case of a feature or bug fix that needs to be merged in multiple versions, you must first merge the commit in the develop branch and then backport the commit to the release. Qualified patches can be backported to previous versions by checking QA regression results therefore the damage to the stability of the previous version can be minimized. If the bug does not occur in develop, it will be merged only in release.

When proceeding the backport, refer to the following process:

• If you want to merge a commit on several versions, you must first merge on the develop branch.

• Check whether the commit first merged in develop branch is stable.

• Applying git cherry-pick would makes the whole backporting easier.

• When a conflict occurs, create a PR which contain 2 commits: one for backporting and one for fixing the conflict.

• If a bug occurs during the backport process, fix it and write down the description of the bug and the fix in the JIRA comment.

Note the following when creating a backport PR:

• When creating a PR, write the PR number merged in develop at the end of the PR title.

  • example)

    • [CBRD-OOOOO] Fix this issue: PR merged in develop#235

    • [CBRD-OOOOO] Fix this issue (#235): PR merged in release/10.2

• Also write down the number of the original PR as follows: You can see that the PR number after the backport is automatically created as a link on GitHub.

If the QA team found a problem with the change merged after verification in the test tool, which greatly affects the QA system, the QA team can revert the commit of the change and return the JIRA issue to the 'CONFIRMED' status. At this point, if the developer decides that the issue needs a triage again, it can revert to the 'OPEN' status.

The failure of resolving the following problems immediately can affect the QA system:

• If some or all of the systems are shut down (a core file is created)

• If the system stops (hang)

• If the behavior is different from that defined in the issue and design documents

• If too many test case failures occur

• If significant performance degradation occurs

If the QA system continues to operate while the above situation persists, then the QA system will be unreliable for the changes which are proceeding simultaneously; therefore, the robustness of the system would be broken, and the subsequent costs of identifying the problem will increase exponentially.

Returning JIRA to the 'OPEN' status means going back to the design, implementation, and code review phase according to the JIRA Workflow. If reconfirmation is required at each step, it is recommended to proceed by creating a feature branch.

Contributions at CUBRID proceed through the following activities.

• Prior Communication: When contributors are looking for any bugs or improvements, suggestions are made to project maintainers and the community.

• Issue Creation: An issue is created when opinions on the content and direction of contribution have been sufficiently collected through prior communication and an agreement to contribute has been reached.

• Pull Request Generation: Issue resolution output, design and code review.

The most important goal of contribution is to encourage contributors to complete their activities. However, communication, which is the beginning of contribution, is the most difficult and cumbersome step because test materials, simple design, and code analysis must be preceded to persuade the project maintainer. Also, it is not easy to find out what kind of improvement is needed for CUBRID in present.

If the project maintainer and the core developer have already agreed on a feature to proceed, but cannot proceed due to lack of resources, the JIRA Issues may be created in advance. Contributors can easily start contributing through these JIRA Issues.

If the JIRA issue described above is set up as a 'Good First Issue' issue, CUBRID can guide the issues that are relatively easy to start for contributors. and contributors can choose among the pre-created issues and can start contributing to CUBRID more quickly and easily.

Once a contributor has been through the contributing process, the contributor will be able to contribute more easily the next time.

'Good First Issue' can be specified on the JIRA Issue label, and it is recommended to create a custom filter and guide.

CUBRID uses Github as a tool for collaboration, such as managing source code and reviewing code as parts of the development progresses. In order to understand the development workflow based on Github, it is recommended to understand the following:

• ​How to use Git​

• Git Branch Model

• Pull Request and Automation Tool

• ​Core Review

When starting a new development item or discovering a bug, you create a JIRA issue. The issue creation process and the items to be filled out are described in the issue creation procedure. Initially, issues are set to the Open status, but to gain approval through triage, you must complete the issue creation and then press the "To Triage" button to forward the issue to the project maintainer.

Subsequently, it is possible to revert from any status back to Open state as needed. During the progression of an issue, if reconfirmation of the issue is necessary at any stage Confirmed, Analysis, Develop, Handover, Resolved), pressing the "Ask Reconfirmation" button will automatically revert the issue’s status to Open and assign it back to the project maintainer. Additionally, even completed (Closed) issues can be reopened if problems arise later by pressing the "Reopen Bug" button, changing the issue's status back to Open.

Issue Creation Procedure

1. After logging in to CUBRID Jira website (jira.cubrid.org), click the "Create" button at the top.

2. In the newly opened "Create Issue" window, fill in each section as described in the following table and click the "Create" button at the bottom.

Issue Types

Component

The component is set in module unit. Components are organized in a hierarchical structure and are increasingly subdivided. You can select multiple components in an issue. The above table are the components available for each project-specific CUBRID project. As shown in the table, CUBRID includes SM, QP, JavaSP, DS, Utility, etc., and each module also includes multiple modules.

When creating an issue, select the relevant module that is known at that time. In the process of investigating an issue, you can additionally select module information related to the issue. For example, in the case of an issue that improves the Buffer Manager in the SM module, you can select CUBRID, SM, or Buffer when creating an issue, and if it affects the File and Lock module while the issue is in progress, you can additionally select the Disk/File AND Lock module.

For projects that affect multiple modules, such as CTE, TDE, JSON, and Java SP, you can create and configure a new component. If necessary, you can ask the project maintainer to create a new component.

Issue Content Template

In the following template, three types of issue are displayed.

Correct Error

• Description: Issue Description

• Repro: Enter the procedure to reproduce the bug. Rather than writing a description of bug reproduction, all procedures such as environment reproduction, schema creation, query execution, and utility execution should be written so that they can be reproduced by copy-paste.

• Expected Result: Expected results (expected results to be fixed)

• Actual Result: Current results (problematic results)

• Additional Information: If there is any additional material or content that can be helpful to understand the bug, please write it down.

Improve Function/Performance, Development Subject, Refactoring

• Description: Issue Description

• Specification Changes: Organize and write the specifications to be changed. It can be used for defining QA tests, writing manuals, etc.

• Implementation: Create design specifications, implementation concepts and details to address issues.

• Acceptance Criteria: Define behaviors/results that must be satisfied within the scope of the issue you have chosen while conducting design and implementation according to your requirements. This content is the basis for the completion to review the design/implementation. If undefined behavior/results are critical, design/implementation needs to be reviewed.

• Definition of done: Write down the criteria of the completion of the issue. You can write as the following example:

  • Satisfies the Acceptance Criteria.

  • Pass the QA test.

Task, internal management

• Description: Write down the purpose and description of the work.

If the CUBRID manual needs to be updated during development or after development is completed, you can contribute in the same manner for and as in the guidelines described in previous sections.

• Manual JIRA: ​

• Manual Github: ​

Specifically, the manual creation process follows the below procedures:

• Create a manual JIRA issue

• Link the created manual JIRA with issues in CBRD or APIS projects

• Create a Pull Request after creating a manual

• Review PR for manual changes and code merge (includes previous versions)

• Change the status of the manual JIRA to 'Done'

First-time contributors to CUBRID are required to submit a CLA (Contribution License Agreement) before contributing the code through a Pull Request. Please refer to the following link for CLA (Contribution License Agreement).

The official communication channels for contributors of CUBRID are (English) and (Korean only).

In addition, you can also communicate with the CUBRID open source community via numerous communication channels such as email, Stack Overflow, Facebook. Twitter, Youtube.

However, communication via the official communication channel (Reddit for English, and Q&A bulletin board for Korean) is strongly recommended.

The Pull Request Format

The subject of a Pull Request (PR) should always include the relevant JIRA issue number. However, aside from the issue number, the title of PR does not have to be same as the title of JIRA. A title that best describes the content of the PR is recommended.

The first line of the description of a PR should always include a link to the relevant JIRA issue because it refers to the design-related content in JIRA for code review. In addition, if you write the purpose, concept, and implementation details (class, function, specific logic) that are not included in the issue or design document, it will be helpful to follow the change of the code of PR later.

• Purpose: Briefly describe the purpose of the code to be merged in the PR.

• Implementation: in addition to the design written in the JIRA issue or design document, describe in detail the logic, class, function, etc. if necessary.

• Remarks: write down the rest of the notes if necessary.

On the right side of the PR, you can set assignee, reviewers, labels, projects, and milestones. When creating a PR, only set assignee and do not use the rest of the fields. Set reviewers before proceeding with code reviews. See the section below.

Code Review

Design review must be completed with the reviewer prior to assigning/requesting a code review. This is because it is difficult to clearly understand the intent and content of the change with code alone. Therefore, design documents (Concept, Architecture) should be shared with project members prior to code review.

• Share the design documents in JIRA

• There is no format for the document

• Reviewers can request material if they need more understanding of the design

After completing the design review, we will proceed with the code review. You can start the code review by assigning reviewers on the right side of the PR.

It is okay to conduct design review and code review at the same time for simple bug fixes or feature implementations with minor changes such as:

• if there are no spec changes

• if there are no changes in function behavior

• if it is small-scale refactoring

Automation Tool (CI)

We are introducing several automation tools into GitHub PR for effective and efficient code review. These tools improve the quality of code and help reviewers not only focus on mistakes but also focus on design and logic issues.

• license: Make sure you have the correct form of the license header comments. If there is a problem, the automation tools will fail, and you can check the 'Details' to see which file the problem was found.

• pr-style: There is a rule that all PRs must be associated with each JIRA issue, and this issue number must be specified at the beginning of the PR title. pr-style will check this and fail if the rule is not followed.

• code-style: Make sure you follow the defined code style to keep your code consistent. Code style is defined using code formatting tools, and code-style uses these tools to check and correct whether the rules are properly followed. If it is different from the rule, it will fail and report it through PR suggestion. Supported languages and code formatting tools include:

  • C: GNU Indent 2.2.11

  • C++: astyle 3.1

  • Java: google java format 1.7

• cppcheck: Static analysis can reveal many problems that developers can cause, such as unused variables and NULL references. These errors are easy to make, but they are obvious, so you can only find them by looking at the code without context. Therefore, it is inefficient for reviewers to find and comment on each one. cppcheck catches these problems. If there is an error, it will fail and report using a comment to the PR. In this case, the report shows the number of errors and warnings. More details can be found in 'Details'. If there are no errors and only warnings, the test passes.

• Build Tests: After PR is applied, check that the build is performed correctly in various environments.

  • appveyor/pr: Windows

  • travis-ci/pr: Ubuntu

  • circleci: build: CentOS 7

• • circleci: test_sql: Create a new database, execute various SQL statements, and check whether the expected results are obtained.

  • cicleci: test_medium: Execute various SQL statements in the database where many tables and data are already created, and check whether the expected results are obtained.

Performing Branch-by-branch Automation Tools

• Build tests and regression tests work on all branches in the repository.

• The rest of the tools only work on develop, feature/* and some release branches (currently release/11.*). Especially for feature branches, you need to apply naming conventions for GitHub checks to work properly.

Guidelines for Failures in Automated Tools Before Code Merge

If the merge button is disabled because some required checks do not pass, the assigned developer must discuss with the project maintainer. In this case, noted that ONLY the project maintainer can merge the 'disabled' PR. project maintainer decide if there is a problem with the automation tool, or an agreement has been reached that the issue reported by the automation tool can be ignored.

The reasons for the above policy is the specification changes and the QA system has not been updated. In this case, it is necessary to communicate and review the failures in the automation tool while making a merge request to the project maintainer.

Request Manual Testing before Code Merge

Before code merging, you can request manual testing by giving the built CUBRID installation file to the QA maintainer to conduct the time-consuming tests which aren't included in PR's automated tools such as shell, HA (high availability), heavy and performance tests.

• After the build, the installation files are transferred to the QA maintainer.

• Test can be time-consuming as it is done manually.

• When the test is completed, you can check the result report of the tested version in 'RB--Manual' on the left tab of the QA Home page.

We recommend that you utilize this manual testing when:

• you can specify the test cases or circumstances that need to be checked

• bugs only occur in a complex environment

  • For example, if it is difficult to find a bug with one SQL and simple debugging, it is good to put a debugging log in the code to find out what is happening and use it to check complex cases by running multiple tests in the QA system environment.

• To avoid indiscriminate consumption of QA resources, do not use this procedure for the purpose of TDD.

Code Merge

You cannot merge code without passing the code review. Code can only be merged if it has passed the automated tool and all 'approved' by reviewers. In this case, the 'Squash and Merger' button is activated and you can create a commit to merge to the CUBRID repository.

When proceeding with 'squash and merger', you must write the message by following this format:

• Title

  • [issue number]

  • the title of the PR

  • Example: [issue number] PR title

• Message

  • First line: the path of the JIRA issue which must be the same as the PR

  • Second line: blank

  • Third line: description of the commit

Example:

Version

Build Number

The build number of CUBRID follows the following rules:‌

• Major.Minor.Patch.Revision

  • e.g) 11.1.0.0512.2d9a03248

  • The patch increases based on the commit count from the time of the previous release.

  • Revision is recorded with the commit hash at the time of build.

Code Name

Before the major and minor versions are released, they have a code name as shown in the following example:‌

• Fruit Name

  • elderberry (11.1)

  • damson (11.0)

  • cherry (10.2), cherry sherbet

  • banana (10.0), banana pie (10.1)

• The version number can always be changed.

• After release, it is managed by the version number instead of the code name.

Release milestones

Major version release follows the following milestones:‌

• Code Freeze

  • CC (Code Complete): All major changes are completed

  • ZAB (Zero Active Bug): All triaged issues are resolved

• ZRB (Zero Resolved Bug): All resolved issues are closed

• FTC (Full Test Complete): Full tests for release are succeed

  • GA (General Availability build): Distribute the release version

Release Procedure

• After Code Freeze, a pre-release branch from develop is created and managed.

• To achieve ZRB, patch regression for major changes in the pre-release branch.

• In ZRB, a full test is conducted for release.

• The patch for the major change applied to the pre-release branch to resolve the regression from the test for release in FTC is ported to develop.

• If the patch is sufficiently verified before the FTC, you can port it with development in advance.

• In GA, pre-release change to release, and pre-release is removed.

In the case of releases and hotfixes of previous versions other than the latest major version, we do not create a pre-release branch but perform a full test for the backported code base.