Development and Review Process

Before we start please keep in mind that “Anything that can go wrong will go wrong - Murphy’s Law”.

Define an architecture before starting development, If the project is more complex break it down into multiple sub projects and define the architecture, In other words do not start an project without an architecture in place, In terms of POC or experiment, that does not have to follow this process, but when the POC is converted into a project it should follow the process.

Architecture

The architecture should follow the below features.

• Scalability
• Security
• Performance
• Maintainability
• Flexibility

The architecture Document should also have why we choose a certain technology/solution the trade-offs between different solutions and evaluate them against the decision-making criteria.

Review

The review process should involve multiple stakeholders and senior members from the team. There should be buy-in from everyone. If there is any conflicts or feedbacks the architecture has to be reworked.

RFC

Every decision has to go through the RFC(Request for Comments) and not deviate from the decisions made. We can use this template

Change in Architecture

If there is a change happening in the architecture it should go back and follow the review process again. Which should also include the area of impact since the architecture has been defined already.

Development Process

Every project should follow the below development process but it can vary in certain cases.

Continuous Integration & Deployment

• Deployments should be automated via CI/CD. This ensures the deployments are repeatable and don’t rely on individual developers or environments.
• Ensure that the project is running automated tests in CI. Successful test completion should be a requirement for deployment.
• Zero-downtime - Rollback options should be available if there is an issue in the build.

Code Review

Reviewing code — and not each other

Why reviews?

Code reviews are an incredibly important part of the development process. Our goals when reviewing code are to:

• expose bugs before they make it to production;
• ensure consistent code quality;
• create an environment for sharing knowledge and developing skills;
• cross-pollinate debugging skills when problems arise;
• cultivate the ability to critique one’s code more strongly;
• encourage open communication between the entire team.

For a successful review

• Remember that we’re reviewing the code, not the author. Nothing should be given or taken personally.
• There is often more than one way to approach a solution. Discuss tradeoffs and reach a resolution quickly.
• Ask questions rather than make statements. (“What do you think about…?”)
• Ask for clarification if the code or comments are unclear. (“I didn’t understand. Can you please clarify?”)
• Avoid selective ownership of code. (“mine”, “not mine”, “yours”)
• Avoid using terms that could be seen as referring to personal traits.
• Be explicit, people don’t always understand your intentions online.
• Be humble. (“I’m not sure — let’s look it up.”)
• Don’t use hyperbole. (“always”, “never”, “endlessly”, “nothing”)
• Don’t use sarcasm.
• Keep it real. If emoji, animated gifs, or humor aren’t you, don’t force them. If they are, use them with aplomb.
• Talk offline if there is too much back and forth. Post a follow-up comment summarizing the discussion.
• Praise team members when they create exemplary work or suggestions.
• Code reviews require intense concentration, don’t forget to factor this in with level of effort estimates.
• Maintaining a well-organized code base requires strict discipline from all team members and will take time and effort to establish; be patient!

For code submitters

• Remember that the code isn’t you, don’t get defensive when a reviewer is critical of the code; instead, look at it as a learning opportunity.
• Seek to understand the reviewer’s perspective.
• Try to respond to every comment.
• Be grateful for the reviewer’s suggestions. (“Good catch, fixing in a4994ec”)
• Explain why the code exists. (“We need to work around these existing patterns”)
• Extract out-of-scope changes and refactoring into future tasks/issues.
• Push commits based on earlier rounds of feedback as isolated commits to the branch. Do not squash until the branch is ready to merge. Reviewers should be able to read individual updates based on their earlier feedback.

For code reviewers

• Understand why the code is necessary (bug, user experience, refactoring) using a peer review.
• Seek to understand the author’s perspective.
• Clearly communicate which ideas you feel strongly about and those you don’t.
• Identify ways to simplify the code while still solving the problem.
• Offer alternative implementations, but assume the author already considered them. (“What do you think about such-and-such here?”)
• Sign off on the pull request with a thumbs up or “Ready to merge” comment.
• Wait to merge the branch until it has passed Continuous Integration testing.
• Use Conventional Comments (opens in a new tab) in order to clarify whether a comment is blocking or non-blocking for merging the PR.

Release

All the projects should release as early and often as possible. The first iteration of your software should not aim to have full functionality; a better goal for the very first release is to have as little functionality as possible.

Big Bang Releases

NO “big bang External releases”. It's recommend, whenever it’s possible, rapid release cycles and iteration, coupled with usability research.

Change log & Versioning

Every repo should have a changelog file with versions.

Guiding Principles

• Changelogs are for humans, not machines.
• There should be an entry for every single version.
• The same types of changes should be grouped.
• Versions and sections should be linkable.
• The latest version comes first.
• The release date of each version is displayed.
• Mention whether you follow Semantic Versioning (opens in a new tab).

Types of changes

• Added for new features.
• Changed for changes in existing functionality.
• Deprecated for soon-to-be removed features.
• Removed for now removed features.
• Fixed for any bug fixes.
• Security in case of vulnerabilities.