Table of Contents
- BitShares Code and Files
- BitShares Core: Projects Guide
- BitShares Core: GitFlow
BitShares offers you to install BitShares-Core into different platforms; Linux:Ubuntu (x64) , OS X , and Windows. There are dependencies to check when you download OpenSSL and Boost. Please make sure which versions you downloaded.
Also, if you are a Windows user, you have other two choices to install BitShares Core to your Windows (x64) Operation System. One is CLI-Wallet tools for Windows (x64) , another one is Windows SubSystem for Linux (WSL) .
The CLI-wallet tools for Windows (x64) allow you to have CLI wallet without the BitShares Core installation. After you download the cli-wallet tools (zip file) and unzip it, you will find all files you need to run CLI wallet.
Another option, Windows SubSystem for Linux (WSL). The WSL is for a developer who uses a Windows 10 (x64) Operation System and wants to build BitShares Core on Ubuntu.
> See System Requirements .
- Open Source program
- Language uses (mainly): BitShares-Core(C++), python
- BitShares GitHub
- BitShares-Core (C++) - BitShares Blockchain implementation and command-line interface.
- Bitshares-FC - Fast-compiling C++ library
- BitShares python - Fully featured client-side library for the BitShares Blockchain - written entirely in python.
- BitShares-UI - Fully featured Graphical User Interface / Reference Wallet for the BitShares Blockchain.
- BSIPs - BitShares Improvement Proposals and Protocols. These technical documents describe the process of updating and improving the BitShares blockchain and technical ecosystem.
The BitShares-Core team is a team of developers who manage the BitShares-Core code and handle the issues that are submitted by other developers. The team creates project plans for next release(s) and delivers the result to the Bitshares community.
- upgrading protocol if needed
- making Project plans for the future release
- creating/ announcing Release
- supporting the BitShares community/ answering questions
- The purpose of this document is to describe and define how changes flow into our code and through the various stages of development until it finally goes into production.
- The general idea is based on git-flow
- For our purposes, the general concept behind gitflow has been extended to allow for these additional needs:
- We have two different types of releases, mainnet and testnet, with a master-like branch for each one.
- We have to distinguish Consensus Impacting Changes (aka hardforks) from Non-Consensus Impacting Changes.
- Maintain two independent release versions, testnet and mainnet.
- Decouple development from releases, i. e. maintain the ability to create emergency bugfixes for current release without bringing incomplete new features into production.
- Separate consensus-related changes from non-consensus-related changes.
- Keep development branches compatible with mainnet.
- Development always happens in private feature-branches. The only exception is a change that must be distinguished in the destination branch (typical example: hardfork date in testnet).
- Features are merged after they are reasonably complete, i. e. they come with unit tests that provide reasonable coverage and do not report any errors.
- “Completed” features that are not consensus-related are merged into “develop”.
- “Completed” features that are consensus-related are merged into the “hardfork” branch, with a hardfork date in the far future.
- All merges into “develop” or “hardfork” are performed via github PR’s and require review and approval from core source (if the PR is created by a core dev at least one other core dev must review and approve).
- To maintain a clean history and make reviewing and merging easier, feature branches must be rebased onto current “develop” (or “hardfork”) before creating a PR.
- Merges are always done as real merges, not as fast-forwards, and not squashed.
- Core devs coordinate regular merges from “develop” into “hardfork”.
- Both “develop” and “hardfork” should always remain compatible with mainnet, i. e. a full replay must be possible.
For a release,
- Bump stuff
- Check whether need to bump
DB_VERSIONto force a replay after upgraded: if there is a data schema change, or logic change that affects historical data, the answer is yes.
- FC version usually has been bumped already during development, but it doesn’t harm if check again.
- Bump docs sub-module which links to wiki.
- A “release” branch is created based on “develop” or “hardfork”.
- The “release” branch is merged into “testnet”.
- For a hardfork release, the hardfork date is adapted directly on the testnet branch.
- The “testnet” branch is tagged as test-version.
- Bugfixes for the release are created on the “release” branch and merged into “testnet”. Additional test-versions are tagged as needed.
- After sufficient testing, the release must be approved. In the case of a hardfork release, witness approval is required.
- After approval, the mainnet hardfork date is decided and set in the “release” branch.
- The “release” branch is merged into “master”, and a version tag is created on “master”.
- The “release” branch is merged back into “develop” and “hardfork”.
- The “release” branch is merged into “testnet”. This will produce a merge conflict for the hardfork dates, which must be resolved without changing the testnet hardfork date.
Doxyfilewith the last version tag. Update online code documentation by using updated
Doxyfileas config file in the
masterbranch. Send pull request to https://github.com/bitshares/bitshares.github.io with new content in html format.Send pull to https://github.com/bitshares/dev.bitshares.works with new content in xml format.
- Update download page of bitshares.org site
- Create binaries for linux, macos and windows. Once the tag name is known create binaries for this 3 OS. Attach them to release notes.
- Example: https://github.com/bitshares/bitshares-core/releases/tag/2.0.181105 Binaries names for this release:
- Linux: BitShares-core-2.0.181105-Linux-cli-tools.tar.gz
- Windows: BitShares-Core-2.0.181105-Windows-x64-cli-tools.zip
- macOS: BitShares-Core-2.0.181105-macOS-cli-tools.tar.gz
Note: Solving conflicts by github(web) will merge branches in unintended directions. Avoid solving this way, merge and resolve conflicts manually through the git command line. Conflicts generally occur when merging release to testnet.
Note 2: Follow command line github suggestion to resolve conflicts but at the end of the process you will not have permission to merge directly to
testnet, never push the fix to
release. Create a new branch and push there, then create a new pull request between
release will be automatically added to the merge.
Note 3: When creating tag for testnet do it from the command line with
git tag. Github don’t have the option to create a tag without a release.
Note 4: the tag commit can be changed. Don’t change tags on github. This is a source of confusion, and of irreproducible bug reports. Make new one is better (ex: test-2.0.180321b or wait 1 day).
Note 5: Do not mark releases as “pre release” unless there is a real new version coming immediately after. Never upgrade “pre release” to “release” as new emails to subscribers will not be sent when doing so.
An emergency fix may become necessary when a serious problem in mainnet is discovered. The goal here is to fix the problem as soon as possible, while keeping the risk for creating additional problems as low as possible.
First of all, the problem must be analyzed and debugged. This happens, naturally, directly on the release version.
Presumably the developer who creates the fix will work on his private master branch. That is OK. But for publishing the fix, the following steps should be taken:
- The fix is applied to the version of the “release” branch that was merged into
masterwhen creating the broken release version.
releasebranch is merged into
master, and a version tag is created on
- Witnesses update to the new version, and production continues.
- A unit test is created on
developthat reproduces the problem.
releasebranch is merged into
develop, and it is verified that the fix resolves the problem, by running the unit test.
releasebranch is merged into