acid-info
/
development-guidelines
mirror of https://github.com/acid-info/development-guidelines.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

proposal init commit

This commit is contained in:
Hossein Mehrabi 2022-11-16 10:10:28 +03:30
parent b2fe754c9e
commit 7579babe90
7 changed files with 369 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -1 +1,6 @@
# Acid.info Development Guidelines
1. [Development Process](/development-process.md)
2. [Branching Strategy](/branching-strategy.md)
3. [Contribution Rules](/contribution-rules.md)
4. [Technology Stack](/technology-stack.md)

44
branching-strategy.md Normal file
View File

@ -0,0 +1,44 @@
- [Introduction](#introduction)
- [The Problem](#the-problem)
- [Strategy Definition Document](#strategy-definition-document)
- [Strategies](#strategies)
- [Useful Links](#useful-links)
## Introduction
This document describes the problem that branching strategies should resolve, what a strategy definition document should be like, and provides links to our current defined strategies. We will continuously review and revise this document and the strategy definitions to ensure they serve their purpose. If you have any suggestions, please make a pull request, or create an issue.
## The Problem
As our projects and team grow, it becomes easier for our codebases and repositories to get messy, making the process of managing changes and delivering the software too complicated or even a nightmare. A well-defined branching strategy will help us keep things organized and consistent, avoid conflicts and increase the team's productivity as long as every contributor abides by it.
We initially planned to seek a strategy that accommodates all types of projects we currently do and may work on in the future. But after doing some research, we found that many other companies have attempted to do the same, but none of them have found a single solution. Therefore, we decided to look into the top commonly used strategies and choose the best fit for each type of project we are currently working on. Then, we adopt that strategy and may slightly change it according to our needs, but in a way that doesn't impose any unnecessary overhead on new contributors; we should try our best to keep it as close as possible to common practices.
## Strategy Definition Document
A strategy definition document should cover the following:
- Introduction
- Branch Types
- Development instructions:
- Create a new feature
- Manage hotfixes
- Undo mistakes
- Create a release
- Create a deployment
- Benefits and Limitations
- Resources
- Examples
- CI/CD setup instruction
## Strategies
Choose a strategy based on the project's type or delivery method.
- [Release delivery](/release-delivery.md)
- [Continuous delivery](/continuous-delivery.md)
## Useful Links
- [Gitflow](https://nvie.com/posts/a-successful-git-branching-model/)
- [GitHub Flow](https://githubflow.github.io/)
- [Gitlab Flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html)
- [Trunk-Based Development](https://trunkbaseddevelopment.com/)
- [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow)
- [War of the Git Flows](https://dev.to/scottshipp/war-of-the-git-flows-3ec2)

127
continuous-delivery.md Normal file
View File

@ -0,0 +1,127 @@
- [Introduction](#introduction)
- [Branch Types](#branch-types)
- [Environment Branches](#environment-branches)
- [Feature Branches](#feature-branches)
- [Hotfix Branches](#hotfix-branches)
- [Contribution Rules](#contribution-rules)
- [Instructions](#instructions)
- [Create a New Feature](#create-a-new-feature)
- [Manage Hotfixes](#manage-hotfixes)
- [Create a Deployment](#create-a-deployment)
## Introduction
This branching strategy is based on [Gitlab Flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html). We will use this strategy for projects that require continuous delivery.
## Branch Types
There are three types of branches:
- Environment
- Feature
- Hotfix
All environment branches should be protected; no one should be able to push commits directly to them.
All non-protected branches are created by developers working on specific tasks and should be deleted once merged.
### Environment Branches
You will have two environment branches on your server:
- `main`
- `production`
Any update to the `main` branch will trigger a deployment to the staging environment, and any update to the `production` branch will trigger a deployment to the production environment. The `production` branch should never be ahead of the `main` branch.
Updates to the `main` branch should trigger a CI action to create a request for merging the `main` with the `production` branch. This merge request may contain a list of tasks for requirements such as manual testing, which should all be marked as done for the maintainer(s) to be able to accept the request.
### Feature Branches
Contributors will mainly work on feature branches. After their work is finished, they will request a merge with the `main` branch.
```mermaid
%%{init: { 'theme': 'base', 'gitGraph': {'showCommitLabel':false,'mainBranchOrder': 1}} }%%
gitGraph
commit
commit
branch production
branch feat-1 order: 2
checkout feat-1
commit
commit
checkout main
merge feat-1
checkout production
merge main
checkout main
```
### Hotfix Branches
A hotfix branch should be first merged with the `main` branch and then cherry-picked into `production`.
```mermaid
%%{init: { 'theme': 'base', 'gitGraph': {'showCommitLabel':false,'mainBranchOrder': 1}} }%%
gitGraph
commit
commit
branch production
branch feat-1 order: 2
checkout feat-1
commit
commit
checkout main
merge feat-1
checkout production
merge main
checkout main
branch feat-2 order: 3
commit
checkout main
merge feat-2
checkout production
branch hotfix-1 order: 4
commit
checkout main
merge hotfix-1
checkout production
merge hotfix-1
merge main
```
## Contribution Rules
See the [contribution rules](/contribution-rules.md) document.
## Instructions
### Create a New Feature
1. Create a local branch:
```bash
$ git checkout -b feat-foo main
```
2. Push your changes to a remote branch with the same name:
```bash
$ git push origin feat-foo
```
3. Create a merge request from your new branch to the `main` branch.
4. Delete your branch after your merge request is approved.
### Manage Hotfixes
1. Create a local branch from the `production` branch:
```bash
$ git checkout -b hotfix-bug production
```
2. Push your changes to a remote branch with the same name:
```bash
$ git push origin hotfix-bug
```
3. Create a merge request from your hotfix branch to the `main` branch.
4. A developer with sufficient permissions may accept the request after all tests are passed and successfully deployed to the staging environment.
5. Create a merge request from your hotfix branch with the `production` branch.
6. A developer with sufficient permissions may accept the request.
7. Delete the hotfix branch on the remote repository once merged.
### Create a Deployment
Updating the `production` and the `main` branches will trigger a deployment.

81
contribution-rules.md Normal file
View File

@ -0,0 +1,81 @@
- [Introduction](#introduction)
- [Code Formatting](#code-formatting)
- [Unit Test](#unit-test)
- [Commits](#commits)
- [Versioning](#versioning)
- [Branching](#branching)
- [Merge Requests](#merge-requests)
## Introduction
This document contains a set of rules and principles that every contributor has to follow while working on our projects. These rules apply to every project regardless of size, development stage, or delivery method. Doing this will allow us to prepare tools and guides to reduce the time to set up new projects, automate release/deployment workflow, reduce communication overhead, and ultimately increase productivity.
## Code Formatting
The code style across all files of the same type should be consistent. Please do not leave the code formatting to the contributor or their editor. Enforce code formatting by defining a Git hook to format staged files before committing. Doing this will ease reviewing merge requests and the project's history. Another important thing is to stick with the conventions while configuring your code formatter.
**For our preferred tech stack:**
1. Install [Husky](https://typicode.github.io/husky/) for Git hooks:
```bash
yarn add -D husky
```
2. Install [Prettier](https://www.npmjs.com/package/prettier) and [Pretty Quick](https://www.npmjs.com/package/pretty-quick) for code formatting:
```bash
yarn add -D prettier pretty-quick && \
npm pkg set scripts.prepare="husky install" && \
npm pkg set scripts.prettier="pretty-quick" && \
npm pkg set scripts.prettier:staged="pretty-quick --staged"
```
2. Create a hook:
```bash
npx husky add .husky/pre-commit "yarn prettier:staged"
```
3. Create a config file for Prettier:
```bash
echo """{
"tabWidth": 2,
"semi": false,
"singleQuote": true,
"trailingComma": "all"
}""" > .prettierrc
```
## Unit Test
TODO.
## Commits
General rules and principles regarding commits:
- **Use [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) messages**:
Enforce conventional commit messages as it is essential for automated semantic versioning. It also helps to understand what's changed by the commit quickly.
- **Short meaningful commit messages that describe an atomic change**:
As a rule of thumb, reverting a commit should not result in side effects other than what you'd expect from the commit message.
A commit message should be short; if it describes more than one distinct change, your commit is not atomic. In this case, you need to break it into multiple commits. To provide more context, add a link to an issue on the remote server by adding `refs #[issue]` or `closes #[issue]` to the commit message.
- **Each commit should contain tests**:
It's good practice to write tests for your changes in the same commit to demonstrate they're working properly.
- **Each commit should contain the updated documentation**
Update the documentation before committing your changes; this way, you won't forget to do it later. Also, it's good to have the documentation in sync with the codes in each commit, and it will prevent causing extra troubles when reverting changes.
## Versioning
All of our projects will use [semantic versioning](https://semver.org/). Since we use conventional commit messages, a version could be determined at any point based on the history of commits.
A summary from the referenced website:
> Given a version number MAJOR.MINOR.PATCH, increment the:
>
> MAJOR version when you make incompatible API changes
> MINOR version when you add functionality in a backwards compatible manner
> PATCH version when you make backwards compatible bug fixes
>
> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
## Branching
Branches deployed to primary pre-defined environments(e.g., staging, production) and the branches you will cut releases from should all be **protected**, and no one should be allowed to push to them directly.
Specify the branch type by choosing a prefix from this list:
- `topic-` for features, issues, chores
- `hotfix-` for hotfixes
## Merge Requests
**Merge only tested and successfully built changes**:
Always ensure all changes will build successfully and pass all the tests. Depending on the project's branching strategy, it might be required to run build and test scripts against all commits.
**Review the changes before merging**:
Merging shouldn't be allowed without at least one review by the project's maintainer(s).

4
development-process.md Normal file
View File

@ -0,0 +1,4 @@
- [Introduction](#introduction)
# Introduction
TODO.

74
release-delivery.md Normal file
View File

@ -0,0 +1,74 @@
- [Introduction](#introduction)
- [Branch Types](#branch-types)
- [Trunk Branch](#trunk-branch)
- [Topic Branches](#topic-branches)
- [Contribution Rules](#contribution-rules)
- [Instructions](#instructions)
- [Create a New Feature](#create-a-new-feature)
- [Manage Hotfixes](#manage-hotfixes)
- [Undo Mistakes](#undo-mistakes)
- [Manage Releases](#manage-releases)
- [Limitations](#limitations)
- [Parallel release branches are not supported.](#parallel-release-branches-are-not-supported)
## Introduction
We take a similar approach to [GitHub flow](https://githubflow.github.io/) for our projects that are delivered through releases.
## Branch Types
There are two branch types:
- trunk
- topic
### Trunk Branch
The trunk is your development branch, the only long-lived branch in your remote server. Use `main` for the name of this branch across all projects for consistency. It will contain your recent well-tested merged changes and must always be release-ready. No one is allowed to push to this branch directly.
### Topic Branches
Contributors will work on short-lived branches and push their changes to the remote server on a branch with the same name. They should then create a request for merging the branch into the trunk. The maintainer(s) may accept the request after reviewing the changes and when all the tests are passed to ensure nothing will break on the trunk branch by merging.
## Contribution Rules
You should strictly follow the [Contribution Rules document](/contribution-rules.md).
## Instructions
### Create a New Feature
1. Create a local branch:
```bash
$ git checkout -b feat-foo main
```
2. Push your changes to a remote branch with the same name:
```bash
$ git push origin feat-foo
```
3. Create a merge request from your new branch to the `main` branch.
4. Delete your branch after your merge request is approved.
### Manage Hotfixes
We treat a hotfix the same as other topic branches; see the instruction for [creating a new feature](#create-a-new-feature).
### Undo Mistakes
TODO.
### Manage Releases
There are two types of releases:
- pre-release
- release
You must automate the process of creating releases and publishing them to repository servers. But triggering the release action should be done manually by the project's maintainer(s), whether by running a script locally or using CI services like GitHub Actions.
By triggering a release, a script will:
1. Decide on a version name based on the commits history since the last release
2. Update the changelog file
3. Update the code with the new version name and the local dependencies in monorepos.
4. Run tests and build the software/packages to make sure everything works well
5. Commit changes on the trunk
6. Create a tag off the trunk with the new version name
7. Push the trunk and the new tag to the remote repository
8. Publish packages to repository servers.
## Limitations
### Parallel release branches are not supported.
Developing multiple versions is not supported in this strategy; as a consequence, you will not be able to release a patch for older major and minor versions, so keep in mind to avoid introducing breaking changes as far as possible.

34
technology-stack.md Normal file
View File

@ -0,0 +1,34 @@
- [Introduction](#introduction)
- [Languages](#languages)
- [Typescript](#typescript)
- [Frameworks](#frameworks)
- [Next.js](#nextjs)
- [Docusaurus](#docusaurus)
- [CI/CD](#cicd)
- [GitHub Actions](#github-actions)
- [Cloud Platforms](#cloud-platforms)
- [Vercel](#vercel)
## Introduction
This document will introduce the programming languages, frameworks, tools, and services we prefer to build and ship software with. It also provides links to tools and guides to help you implement [contribution rules](/contribution-rules.md) and a [branching strategy](/branching-strategy.md) when setting up a new project.
Choosing the right tech stack depends on multiple factors, such as the software type, functionalities, and requirements. It's impossible to cover all possibilities, nor is it our intention. But we encourage contributors to choose their stack as close as possible to what is covered here, so that other contributors would be familiar with it. Also, this will allow us to prepare guides and tools for implementing our development workflow once and use them in multiple projects.
## Languages
### Typescript
We use javascript because its ecosystem lets us build almost any software; this is important for the reasons we explained in the [introduction](#introduction).
Not being a type-safe language, Javascript increases the chance of runtime errors and makes it extremely hard to read and maintain the project as it or the team working on it gets bigger. We prefer Typescript over Javascript because it has solved these issues, ensuring that we deliver safer software.
## Frameworks
### Next.js
### Docusaurus
## CI/CD
### GitHub Actions
## Cloud Platforms
### Vercel