diff --git a/Development_Documents/BOINC_Flow.md b/Development_Documents/BOINC_Flow.md new file mode 100644 index 0000000..b7b91fe --- /dev/null +++ b/Development_Documents/BOINC_Flow.md @@ -0,0 +1,58 @@ +# BOINC Flow +There are many successful approaches to branching with git. The BOINC community is using the following model that derives heavily from approaches like Microsoft's [Release Flow](https://docs.microsoft.com/en-us/azure/devops/devops-at-microsoft/release-flow) and [GitLab Flow](https://docs.gitlab.com/ee/workflow/gitlab_flow.html) but customizes these approaches to suit the needs of the BOINC community. + +## Master Branch +The master branch is the primary branch in the project. Committers will never commit to the master branch directly. Any code merged into master is expected to go through peer review, be unit tested and have had existing automation tests run successfully against the new code before it is merged. As a result, the master branch is expected to be reliable and is what developers should usually branch from when creating other branches. + +## Feature and Bugfix Branches +Developers create feature or bugfix branches when they want to modify the code base. If they are a committer, then they can use the [shared repository model](https://gist.github.com/seshness/3943237) and create the branch within the BOINC project directly. If they are not a committer then they should follow the [fork and pull approach](https://gist.github.com/Chaser324/ce0505fbed06b947d962) to create a branch and submit a pull request. + +Features and bugfix branches are merged into master via a pull request. Developers should understand what is expected before submitting a pull request by reviewing the [Development Workflow](Development_Workflow.md) document. + +Once a feature or bugfix branch has been merged into master it should be deleted. + +The majority of the code contributed to the project is developed using a feature or bugfix branch. + +

+Diagram of Feature and Normal Bugfix Branches +

+ +## Release Branches +BOINC has two types of releases: client releases and server releases. Each of these require additional integration and end user testing that is not usually done for each individual feature or bugfix branches. This additional testing needs to be conducted against a stable code base (code freeze) while also allowing development for future work to continue. The way to do this is to create a release branch. The release branch freezes the code that is being tested. Other development can continue on the master branch without impacting the release branch. + +A release branch is created off of the master branch. Since the release branch is considered feature frozen, new code should only be added to the branch if the release manager determines that it is necessary. + +Any code that is added to a release branch after it is created should be a cherry-pick of a merge commit that is present on the master branch. The merge commit would be the result of a merging a bugfix or feature branch. See below for the preferred way to create a bugfix branch that is intended for inclusion in a release. + +Release branches are never deleted. + +

+Diagram of a Release Branch +

+ +## Bugfix Branch intended for a Release +Branches for bugfixes that are intended to be included in an existing release branch should be handled carefully in order to minimize the chance of including unrelated code into the release branch. This can be done by creating the bugfix branch from the same commit where the release branch was created. In order to do this, you need to identify the commit that served as a base for the release branch and then create the bugfix branch from that commit. + +For example, if you were creating a bugfix branch for 7.12 client release you would do the following: +``` +[knreed@localhost boinc]$ git merge-base master client_release/7/7.12 +aa6e1fac07a7fd826218b2ac16a810a76413dfba +[knreed@localhost boinc]$ git branch knr_fix_issue_1234 aa6e1fac07a7fd826218b2ac16a810a76413dfba +``` + +This is the recommended and suggested approach whenever possible for handling bugfixes for a release branch. + +

+Diagram of a Bugfix Branch intended for a Release +

+ +## All Together +As an example of how all of these branches work together, the image below shows master, feature, bugfix and release branches as they might occur in normal development. + +In this example, the release manager was waiting for Feature A to be merged into master so that it could be included in the next release. Once it was, they created the 7.12 release branch from master and began working leading the community in testing the release. During the testing a critical bug was uncovered. A bugfix branch was created off of master to fix the bug and the bugfix branch was merged back into master. The bugfix was included in the release by cherry-picking the merge commit into the release branch. + +While the release was being tested, work on Feature B continued and was merged into master. That will be included in a future release. + +

+Diagram of a multiple branches +

diff --git a/Development_Documents/Client_Release_Process.md b/Development_Documents/Client_Release_Process.md new file mode 100644 index 0000000..0274226 --- /dev/null +++ b/Development_Documents/Client_Release_Process.md @@ -0,0 +1,97 @@ +# Client Release Process +The purpose of this document is to define the client release process at a high level, establishing a standard process so that the community knows what to expect and where they can help with new versions of the client. In order to understand this process, it is useful to first understand the [development workflow](Development_Workflow.md) and [BOINC Flow (Branch and merge strategy)](BOINC_Flow.md). + +## Overview +The release process will produce some or all of the following items: +- Downloadable binaries for a new version of the client software for: + - 32 bit Windows (one with VirtualBox and one without) + - 64 bit Windows (one with VirtualBox and one without) + - 64 bit OSX +- Updated application in the Google Play Store +- Updated versions of the Linux client by the package maintainers for EPEL and Debian +- Documentation about features +- Release notes / version history +- Announcements + +In order to produce this, the following need to be updated, built, and tested: +- The code used to build the binaries +- Dependent libraries +- Copyright and other legal information +- Installer definitions +- All text included in screen displays, messages, etc. +- Translations of text +- Test cases and their outcomes +- Any included data (e.g. 'all projects list' and ca-bundle) + +## Roles +The process of releasing the client requires the work of a number of people in the community. As such there are some additional roles that are useful to define for this process. Note that one person can serve in one or more roles during the process (for example, one person can be the release manager as well as the build master for Windows). + +### Release Manager +The release manager is the person who manages the release process. He or she is responsible for the communications and coordination required to get the release built, tested, and announced. Some of the things the release manager is expected to do are: +- Announce the intention to make a new release of the client +- Ask if anyone has anything that they are working on that they want to include the release. +- Determine when to create the release branch +- Coordinate the builds of the client +- Coordinate the testing of each build of the client +- As bugs are found during testing, identify which ones will be fixed and included in the current release vs deferred to a future release +- Ensure that all required items that need to be updated in the release have been updated (see list of items produced in a release in the overview above) +- Call for a consensus vote of committers to determine if a build is ready to be declared as generally available +Throughout the process, the release manager is expected to communicate what is going on as the work progresses and make sure to address concerns that are raised as the work progresses. + +### Build Master +Someone needs to be responsible for building the clients for each of Windows, Mac, Linux, and Android. It can be a different person or the same person for each platform. These people will be responsible for creating official builds when the release manager requests a new build. Build masters will work with the PMC in order to gain access to any signing keys or login rights required to create builds for their platforms. + +The build masters will work with the release manager in order to ensure that new builds are created at the requested times as the release work proceeds. + +### Testers +People who want to help test the client releases should be familiar with the [Alpha Testing](https://boinc.berkeley.edu/trac/wiki/AlphaInstructions) wiki page and associated processes. + +## Process +### Prepare for a Release +The release manager will announce the intention to make a new release of the client. When they do this they should make a request to the community to find out if there is any work in progress that will be available shortly that should be included on the request. The release manager will work with anyone who responds to determine if that work will be included or not depending on the relevant concerns at the time. + +The release manager should also connect with the build masters and confirm with them that they are available for creating builds during the next several weeks as the work progresses. + +The release notes should be created/updated each time a build is made from a release branch. The information in the release notes should contain the new features and important bugs fixed since the previous release. They should be recorded in a style similar to this: https://boinc.berkeley.edu/wiki/Release_Notes_for_BOINC_7.6. + +### Release Branch +The release branch is created once the release manager has decided that all work that will be included in the release is available in the master branch. Once a release branch is created, it is expected that the community will work to quickly test and make the release available for general use. The release manager and the community should try to avoid having releases that take longer than two to three weeks between the creation of a release branch and making the release generally available. + +The release branch is feature frozen. This means that no new features should be added to the release once the release branch is created. Additionally, only important bug fixes should be merged into the release branch. The release manager makes the final decision about what, if any, changes will be merged into the release branch. + +All code merged into the release branch will be a cherry-pick based on a merge commit. + +Please read [BOINC Flow](BOINC_Flow.md) for more details about how feature branches, bugfix branches and release branches are used by the BOINC community. + +### Build and Test +The build and test cycle for the client is done by leveraging the supporters who are willing to test the client through the process outlined on the [Alpha Testing wiki page](https://boinc.berkeley.edu/trac/wiki/AlphaInstructions). + +The test process should roughly follow the following path: +- The release manager increments the build version number and asks the build masters to create a new build of the client +- At this stage the build number should use an odd 'minor' number as it is considered a test build. Ex: 6.11.20 +- The release manager updates (or asks someone to update for them) the version history with a list of significant changes since the last build +- Once the builds are available, the release manager sends an email to the boinc-alpha email list announcing the availability of a new release candidate and points them to the version history page. The release manager asks the testers to start a new round of testing +- Testers conduct testing and record bugs found +- The release manager monitors bugs being reported and designates those that need to be fixed in this release and those that can be fixed for a future release. The release manager should inform the community on boinc-alpha about which bugs are to be fixed and which are to be deferred to a future release. The release manager should respond to comments and different perspectives about these decisions and consider carefully the feedback from the community. +- Repeat after designated bugs have been fixed + +### General Acceptance +The build and test cycle repeats until there are no bugs remaining that have been designated to be fixed in this release. Once this occurs, the release manager will increment the version number so that the 'minor' version is even indicating that this is a release candidate. He or she will then ask the build masters to rebuild the clients using the new version number. + +After the testers perform a lightweight regression test of the new builds and no new bugs are found, the release manager will call for a consensus vote of the committers to declare the build as generally available. If the vote succeeds, then the BOINC website is updated to reflect the status of the release as generally available. + +### Post Release Management +It is inevitable that additional bugs will be found once the software is released to the general public. The release manager, build masters and testers should expect to remain engaged for several weeks following general availability of a release and continue to track bug reports that come in from end users. The release manager will continue to lead the community through the process of prioritizing these bugs, and determine if they need to be fixed in the current release with a new build, or if they can be deferred until a future release. If the release manager decides that a bug needs to be fixed, then the release manager will lead the community through another build and test cycle that includes the fixes for the designated bugs. + +## Appendix +### Version Numbering +The BOINC client uses the following in its release numbering: + +Major.Minor.Build +- The major is incremented when a significant and fundamental change is made to the client. The release manager shall decide when a release constitutes a significant enough change to merit incrementing the major version number. +- Odd minor version numbers indicate that the version is a test build. +- Even minor version indicate a release candidate or a generally available release. +- Build version numbers are incremented each time a new build is made. + +# Document Change Process +This document can be updated by following the process documented in section 6.2 of the [Governance](../Governance_Documents/Governance.md#62-development-documents) document. \ No newline at end of file diff --git a/Development_Documents/Development_Workflow.md b/Development_Documents/Development_Workflow.md index 8a73ce2..66e0e46 100644 --- a/Development_Documents/Development_Workflow.md +++ b/Development_Documents/Development_Workflow.md @@ -39,7 +39,7 @@ Reviews are expected to examine two things: If a change is approved, the issue should be "ready to implement" and should be added to the project board for its respective area (https://github.com/BOINC/boinc/projects). Committers are expected to also prioritize issues and have a small collection of the highest priority issues in the To-Do column of the different project boards. This makes it easy for developers to find work that needs to be done and also helps with facilitation of the overall development process. ## 2. Implementation -All development is done using feature branches as defined in [GitHub Flow](https://guides.github.com/introduction/flow/). BOINC uses the [Fork and Pull Model](https://gist.github.com/Chaser324/ce0505fbed06b947d962) for development (background on this approach can be [read here](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/)). Once you have created your fork, set it up locally, and created a feature branch, then you can begin coding. When you are finished with development you can create a pull request for review. +All development is done using feature branches as defined in [BOINC Flow](BOINC_Flow.md). BOINC uses the [Fork and Pull Model](https://gist.github.com/Chaser324/ce0505fbed06b947d962) for development (background on this approach can be [read here](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/)). Once you have created your fork, set it up locally, and created a feature branch, then you can begin coding. When you are finished with development you can create a pull request for review. Make sure to review the [Definition_of_Done_for_Feature_Branches.md](Definition_of_Done_for_Feature_Branches.md) before starting work so that you are familiar with the expectations of your work. diff --git a/Development_Documents/images/AllBranches.png b/Development_Documents/images/AllBranches.png new file mode 100755 index 0000000..729f970 Binary files /dev/null and b/Development_Documents/images/AllBranches.png differ diff --git a/Development_Documents/images/BugfixBranch.png b/Development_Documents/images/BugfixBranch.png new file mode 100755 index 0000000..a770404 Binary files /dev/null and b/Development_Documents/images/BugfixBranch.png differ diff --git a/Development_Documents/images/FeatureBranch.png b/Development_Documents/images/FeatureBranch.png new file mode 100755 index 0000000..e2c253e Binary files /dev/null and b/Development_Documents/images/FeatureBranch.png differ diff --git a/Development_Documents/images/ReleaseBranch.png b/Development_Documents/images/ReleaseBranch.png new file mode 100755 index 0000000..d380a0d Binary files /dev/null and b/Development_Documents/images/ReleaseBranch.png differ diff --git a/README.md b/README.md index 9a4d8c9..66a9fdb 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ The following documents describe how the project is organized and how the projec The following documents describe the development workflow and related processes. * [Development Workflow](Development_Documents/Development_Workflow.md) +* [BOINC Flow - Branch and Merge Strategy for BOINC](Development_Documents/BOINC_Flow.md) +* [Client Release Process](Development_Documents/Client_Release_Process.md) * [Definition of Done for Feature Brances](Development_Documents/Definition_of_Done_for_Feature_Branches.md) * [Expectations of Code Review](Development_Documents/Expectations_of_Code_Review.md)