update the v0 proposal.
This commit is contained in:
Hossein Mehrabi
parent
afb684860c
commit
72565a8de0
|
|
@ -1,6 +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)
|
||||
- [Development Process](/development-process.md)
|
||||
- [Branching Strategy](/branching-strategy.md)
|
||||
- [Contribution Rules](/contribution-rules.md)
|
||||
- [Technology Stack](/technology-stack.md)
|
||||
|
|
|
|||
|
|
@ -90,12 +90,12 @@ See the [contribution rules](/contribution-rules.md) document.
|
|||
### Create a New Feature
|
||||
1. Create a local branch:
|
||||
```bash
|
||||
$ git checkout -b feat-foo main
|
||||
$ git checkout -b topic-foo main
|
||||
```
|
||||
|
||||
2. Push your changes to a remote branch with the same name:
|
||||
```bash
|
||||
$ git push origin feat-foo
|
||||
$ git push origin topic-foo
|
||||
```
|
||||
|
||||
3. Create a merge request from your new branch to the `main` branch.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
- [Introduction](#introduction)
|
||||
- [Code Formatting](#code-formatting)
|
||||
- [Unit Test](#unit-test)
|
||||
- [Commits](#commits)
|
||||
- [Commit Messages](#commit-messages)
|
||||
- [Unit Testing](#unit-testing)
|
||||
- [Documentation](#documentation)
|
||||
- [Versioning](#versioning)
|
||||
- [Branching](#branching)
|
||||
- [Merge Requests](#merge-requests)
|
||||
- [Code Review](#code-review)
|
||||
|
||||
## Introduction
|
||||
|
||||
|
|
@ -13,7 +15,7 @@ This document contains a set of rules and principles that every contributor has
|
|||
## 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:**
|
||||
**Setup code formatting for JS/TS projects:**
|
||||
1. Install [Husky](https://typicode.github.io/husky/) for Git hooks:
|
||||
```bash
|
||||
yarn add -D husky
|
||||
|
|
@ -38,21 +40,27 @@ echo """{
|
|||
"trailingComma": "all"
|
||||
}""" > .prettierrc
|
||||
```
|
||||
## Commit Messages
|
||||
**Use [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) messages:**
|
||||
Writing conventional commit messages should be enforced as it is essential for automated semantic versioning. It also helps to understand what's changed by the commit quickly.
|
||||
|
||||
## Unit Test
|
||||
TODO.
|
||||
**Write 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.
|
||||
|
||||
## 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.
|
||||
**Tools:**
|
||||
- [Commitizen](https://github.com/commitizen/cz-cli): enforce conventional commits.
|
||||
|
||||
## Unit Testing
|
||||
**Each project should have a configured unit testing framework:**
|
||||
Setup a unit testing framework when you start a new project and create a template unit test to help and encourage contributors to write tests.
|
||||
|
||||
**Write unit tests for your changes in the same commit:**
|
||||
It's good practice to write tests for your changes in the same commit to demonstrate they're working correctly.
|
||||
|
||||
## Documentation
|
||||
**Update the documentation according to your changes in the same commit:**
|
||||
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.
|
||||
|
|
@ -74,8 +82,18 @@ Specify the branch type by choosing a prefix from this list:
|
|||
- `hotfix-` for hotfixes
|
||||
|
||||
## Merge Requests
|
||||
**Merge only tested and successfully built changes**:
|
||||
**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).
|
||||
**DO NOT squash commits:**
|
||||
Since we rely on conventional commits, squashing commits upon merging can break our workflow. It might also make finding the reason behind a particular change challenging. Note that it's not the maintainer's job to clean up the contributor's work history; the maintainer should ask for another pull request.
|
||||
|
||||
**Review the changes before merging:**
|
||||
Merging should only be allowed with a review or approval from the project's maintainer(s).
|
||||
|
||||
## Code Review
|
||||
**Ensure the changes are aligned with the contribution rules:**
|
||||
It's the maintainer's responsibility to ensure all changes in a merge request are aligned with our contribution rules described in this document and the project's branching strategy.
|
||||
|
||||
**Ask to add the missing unit tests:**
|
||||
It's the maintainer's responsibility to ensure no necessary important unit test is missing.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,51 @@
|
|||
- [Introduction](#introduction)
|
||||
- [Summary](#summary)
|
||||
- [Starting a New Project](#starting-a-new-project)
|
||||
- [Development Workflow](#development-workflow)
|
||||
|
||||
# Introduction
|
||||
TODO.
|
||||
## Summary
|
||||
The development process takes place after a product's functionalities and specifications are determined and the development team's requirements to begin this process are arranged. These requirements may include designs or user flows, access to third-party services, etc. The development team's first step is to decide on the software's architecture and structure and set up a development environment. Then, the implementation stage begins; how the team will plan to proceed in this stage depends on multiple factors, such as the software's delivery method, business requirements, and timeline.
|
||||
|
||||
The following sections will walk you through
|
||||
- Initial steps for starting a new project
|
||||
- Development and maintenance workflow
|
||||
|
||||
## Starting a New Project
|
||||
The following are the initial steps you will need to take when starting a new project. Ideally, you will follow the steps as they are described below. Still, depending on the project's timeline and other unpredictable circumstances, you might proceed differently or repeat the steps as the project's plan and its requirements change.
|
||||
|
||||
**1. Software architecture:**
|
||||
The team's requirements to start working on the project are arranged at this stage. The project's lead developer(s) will decide on the software architecture.
|
||||
|
||||
**2. Decide a tech stack:**
|
||||
The project's lead developer will decide on a tech stack at this step by taking the team's experience into account but generally should try to keep it as close as possible to [our preferred stack](/technology-stack.md).
|
||||
|
||||
**3. Adopt a branching strategy:**
|
||||
The team will adopt a branching strategy based on the software's delivery method from the [Branching Strategy](/branching-strategy.md#strategies) document.
|
||||
|
||||
**4. Setup a development environment:**
|
||||
The project's lead developer will assign a developer who most likely has the most experience with the chosen tech stack and branching strategy to set up a development environment. The developer will prepare the project's initial code and tools and collaborates with the infrastructure team to set up the repository rules and CI/CD pipelines.
|
||||
|
||||
## Development Workflow
|
||||
This section only describes our development workflow abstractly; your project branching strategy may introduce some additional steps.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A(Submit Change) --> B[Perform Tests]
|
||||
--> B1{Pass}
|
||||
B1-- Yes --> C[Code Review]
|
||||
B1-- No --> A
|
||||
C--> C1{Acceptance}
|
||||
C1-- No --> C2[Request for Change] --> A
|
||||
C1-- Yes --> D[Merge]
|
||||
```
|
||||
|
||||
**1. Submit Changes:**
|
||||
Contributors will always submit their work through merge requests.
|
||||
|
||||
**2. Testing:**
|
||||
Upon creating/updating a merge request, tests will be run against the changes to ensure they won't break anything and the software will build successfully. The request will go to the next step if all the tests are passed.
|
||||
|
||||
**3. Code Review:**
|
||||
The project's maintainer is responsible for reviewing merge requests and ensuring all the changes are aligned with our [contribution rules](/contribution-rules.md).
|
||||
|
||||
**4. Release/Deploy:**
|
||||
Managing releases and deployments are either automated or done manually by the project's maintainer(s) according to the project's branching strategy.
|
||||
|
|
|
|||
|
|
@ -25,6 +25,24 @@ The trunk is your development branch, the only long-lived branch in your remote
|
|||
### 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.
|
||||
|
||||
```mermaid
|
||||
%%{init: { 'theme': 'base', 'gitGraph': {'showCommitLabel':false,'mainBranchOrder': 0}} }%%
|
||||
gitGraph
|
||||
commit tag: "v1.0.0"
|
||||
branch topic-foo
|
||||
checkout topic-foo
|
||||
commit
|
||||
commit
|
||||
checkout main
|
||||
merge topic-foo
|
||||
commit tag: "v1.1.0"
|
||||
branch topic-fix
|
||||
commit
|
||||
checkout main
|
||||
merge topic-fix
|
||||
commit tag: "v1.1.1"
|
||||
```
|
||||
|
||||
## Contribution Rules
|
||||
You should strictly follow the [Contribution Rules document](/contribution-rules.md).
|
||||
|
||||
|
|
@ -33,12 +51,12 @@ You should strictly follow the [Contribution Rules document](/contribution-rules
|
|||
### Create a New Feature
|
||||
1. Create a local branch:
|
||||
```bash
|
||||
$ git checkout -b feat-foo main
|
||||
$ git checkout -b topic-foo main
|
||||
```
|
||||
|
||||
2. Push your changes to a remote branch with the same name:
|
||||
```bash
|
||||
$ git push origin feat-foo
|
||||
$ git push origin topic-foo
|
||||
```
|
||||
|
||||
3. Create a merge request from your new branch to the `main` branch.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,25 @@
|
|||
- [Introduction](#introduction)
|
||||
- [Languages](#languages)
|
||||
- [Typescript](#typescript)
|
||||
- [Use Cases](#use-cases)
|
||||
- [CSS/SCSS](#cssscss)
|
||||
- [Use Cases](#use-cases-1)
|
||||
- [Libraries](#libraries)
|
||||
- [React](#react)
|
||||
- [Use Cases](#use-cases-2)
|
||||
- [Frameworks](#frameworks)
|
||||
- [Next.js](#nextjs)
|
||||
- [Use Cases](#use-cases-3)
|
||||
- [NestJS](#nestjs)
|
||||
- [Use Cases](#use-cases-4)
|
||||
- [Docusaurus](#docusaurus)
|
||||
- [Use Cases](#use-cases-5)
|
||||
- [CI/CD](#cicd)
|
||||
- [GitHub Actions](#github-actions)
|
||||
- [Use Cases](#use-cases-6)
|
||||
- [Cloud Platforms](#cloud-platforms)
|
||||
- [Vercel](#vercel)
|
||||
- [Use Cases](#use-cases-7)
|
||||
## 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.
|
||||
|
||||
|
|
@ -20,29 +32,40 @@ We use javascript because its ecosystem lets us build almost any software; this
|
|||
|
||||
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.
|
||||
|
||||
#### usecases
|
||||
#### Use Cases
|
||||
|
||||
### CSS/SCSS
|
||||
#### usecases
|
||||
#### Use Cases
|
||||
|
||||
## Libraries
|
||||
### React
|
||||
#### usecases
|
||||
#### Use Cases
|
||||
|
||||
## Frameworks
|
||||
|
||||
### Next.js
|
||||
#### usecases
|
||||
[Next.js](https://nextjs.org/) is an open-source [React](https://reactjs.org/) framework created by [Vercel](http://vercel.com/). We build frameworks on top of it to speed up our website development process.
|
||||
#### Use Cases
|
||||
- A framework that empowers Logos brands to build websites under the design system of Logos. See [here](https://github.com/acid-info/logos-site-builder).
|
||||
|
||||
### NestJS
|
||||
#### Use Cases
|
||||
|
||||
### Docusaurus
|
||||
#### usecases
|
||||
[Docusaurus](https://github.com/facebook/docusaurus) is an open-source [React](https://reactjs.org/) framework created by Facebook for building documentation websites, which supports i18n, versioning, custom pages, MDX documents, customized themes, etc.
|
||||
|
||||
#### Use Cases
|
||||
- Create highly customized documentation websites for Logos business units. (see [codex.storage](https://codex.storage), [here](http://github.com/acid-info/logos-documentation-website-template), and [here](https://github.com/acid-info/logos-docusaurus-plugins))
|
||||
|
||||
## CI/CD
|
||||
### GitHub Actions
|
||||
#### usecases
|
||||
#### Use Cases
|
||||
|
||||
## Cloud Platforms
|
||||
|
||||
### Vercel
|
||||
#### usecases
|
||||
We only intend to use Vercel for demo and test cases, but we're also temporarily deploying multiple Logos brands' websites on it.
|
||||
|
||||
#### Use Cases
|
||||
- Quickly deploy websites for demo & test cases
|
||||
- Setup CI/CD pipelines and deploy Logos brands websites ([vac.dev](http://vac.dev/), [waku.org](https://waku.org/), [codex.storage](https://codex.storage))
|
||||
Loading…
Reference in New Issue