Current development workflow
Right now we have these projects:
- Core API
- Backend services
- Bitmark SDK
Our current workflow uses OKR, where we define sprints as a deadline to deliver the software artefact, but we do not limit ourselves. We do translate the OKR in ISSUES on GitHub where we can track them. The external contributors can get involved with the project opening new ISSUES, being part of the discussion in existent ISSUES and make PULL REQUESTS within our projects.
Branch, Tag and release process:
We have a single development branch master, from where we create tags to perform minor and major releases. The development never happens directly on branch master, instead the developer create a development branch from master, after the developer believes its branch is ready, it opens a pull request and assign another developer to make a review. After the review process, the developer merges its branch to master branch and deletes the development branch. The developers never commit directly into the master branch without passing through the review process.
We have a peer review process, where the developer can assign one or more individuals to verify its code, these individuals shall suggest modifications or accept the pull request, also the reviewer can reassign the review. Currently there are no time outs specified for reviewers, and in such a case, if a reviewer is delaying the review, it must discuss during the stand-up daily meeting.
Development work-flow improvements
This is our working flow using GitHub. Here I describe 3 basic areas of our development process.
What to do when there is a new patch?
First, we need to ask ourselves, is it a trivial patch? In case it is not a 3-lines change patch, it means, it is not a trivial patch, sometimes even a 3-lines change is not trivial. We do need to be mature enough to understand what is and what is not a trivial patch. In case it is not a trivial patch, we shall open a GitHub issue with a proper title and describe what is the problem we are trying to fix, following with a pull request with a patch (if we have one), this patch must point out to the issue number. All the discussion related to implementation, shall be in the issue, code problems shall be in the pull request.
I would like to stress a bit how to perform a proper code review:
We need to always remember, there are other people watching us, the information is on the Internet and it will always be there, we need developers to engage with us, perhaps we need companies out there to see us relevant and join our cause.
What to do:
- Know what is under review, understand what the developer is trying to achieve.
- Know what to look for in code: Structure, Style, Logic, Performance, Test coverage, Design, Readability, Maintainability and Functionality.
- Does it pass on CircleCI/TravisCI and Jenkins? Otherwise don’t need start to make a review.
- Build and test.
- Give feedback that helps and not hurt, be impartial, as much as somebody prefers BLUE, some other people prefer YELLOW, so be impartial.
- Communicate goals and expectations, we use Slack and if we have direct access to the person that opened the code review, instead to go and make a comment and wait the person reply, talk directly with the person, it saves time and foster a positive culture.
- Peer review is all about trust, we need to be glad somebody is asking us to review its code.
- Be nice, at the end of the day, there is no software made by only one person.
- If the pull request comes from an outsider contributor, be nicer than usual, even if it is necessary to fix any code before merge and give all the credits to him/her, we need this person to come back and start to contribute more often. So, don’t be harsh with newcomers.
- Remember, when doing a code review it might takes 30 minutes, but the person that made the code might have spent weeks, so be empathetic.
What not to do:
- Broken English, most of us are not native speakers, there is no problem to use Google translation to help us when we want to write something, especially when it is public.
- Be specific and with short sentences, go direct to the point.
- Nobody really cares if someone else prefer “for” or “while”, so don’t nit-picking other people’s code, it is demotivating.
- Don’t do unsolicited code review..
- No power struggling in public, nobody will become “millionaire” bashing each other.
- Don’t write big messages, short sentences are easier to understand, go to slack, send an email or make a phone call in case the peer works at Bitmark Inc..
- Don’t be too verbose and pedantic.
Before opening a pull request:
Make sure everything is in place, when a pull request is open, it means the code is ready for review. Here are some steps before open a pull request.
- Does the code needs a broad discussion with other peers?
- How critical is the impact of these changes?
- Is there a GitHub issue explaining what this code is about?
- Is it a new feature? Do we have a software design document with the result of all discussion? (prior to code or prototype)
- The tools, misspell, go test and go build, did run fine, didn’t it?
- Does the code does what it proposes?
- Does the code follows the Golang specification? https://golang.org/ref/spec
- Will reviewers know how to test and validate it?
- Is there enough coverage with unit tests?
- Does the commit history has a clear and concise message?
- Does it needs documentation?
- Does it needs QA?
- Does this fix/feature needs to be part of the next release?
- Do we need extra validation like run on Testnet for a while?
The quality assurance team must focus on the number of issues closed and must be part of the next RELEASE, they also have the power to control what can and cannot be part of the next RELEASE, they shall be in charge to stabilize the software and make sure the documentation is update. They also must help to prepare the RELEASE notes.
To make the software stable, we need to stabilize a branch and let the Developers test it and give time for QA to validate it prior to RELEASE it and also we need to enforce a freeze time where the branch won’t receive any critical change or new feature.
Code freeze and QA steps:
- We must set a group of features or fixes as a milestone for the next RELEASE, best would be to have a ROADMAP or MoSCoW for a particular version.
- We schedule a candidate date for the RELEASE.
- We announce the freeze time.
- Branch stable-version from master.
- Freeze branch master and stable.
- If QA find a regression, the fix must first goes into master and from there cherry-picked to stable.
- QA must validate it first prior the PR merges into master and stable.
- Release the software.
- Unfreeze branch master.
The release process is a critical path that ensures we will accomplish the stakeholders requirements and deliver the intended objectives. Also it establishes a routine of communication internally and external, stakeholders, developers and users have a standard to follow and knows what to expect from the project.
- Planning the release, what features shall be in this version, what bug fixes if we know beforehand, documentation update, users communication and so on.
- Initial feature specification in a high level description, more detailed and technical specification (issue), code, PR and merge.
- Build a release candidate and eat our own dog food.
- QA verification trying to automate as much as possible any test.
- QA tests, all GREEN, QA gives Acceptance, CTO pushes the GO button.
- Build the official release and release notes.
- QA and team validation.
- Release rolled out.
- Public communication.
- Bitmark Inc. internal release validation (mimic an end user).