From 6484c32e2628ea72e43c6bffe13e958c091acf18 Mon Sep 17 00:00:00 2001 From: "Xinwei Xiong(cubxxw-openim)" <3293172751nss@gmail.com> Date: Wed, 5 Jul 2023 22:36:15 +0800 Subject: [PATCH] docs: add more docs help deployer Signed-off-by: Xinwei Xiong(cubxxw-openim) <3293172751nss@gmail.com> --- docs/contrib/cicd-actions.md | 8 +-- docs/contrib/development.md | 80 +++++++++++++++++++++++++++ docs/contrib/git_workflow.md | 102 +++++++++++++++++++++++++++++++++++ 3 files changed, 187 insertions(+), 3 deletions(-) create mode 100644 docs/contrib/development.md create mode 100644 docs/contrib/git_workflow.md diff --git a/docs/contrib/cicd-actions.md b/docs/contrib/cicd-actions.md index 7a581d3fa..2a95860be 100644 --- a/docs/contrib/cicd-actions.md +++ b/docs/contrib/cicd-actions.md @@ -1,6 +1,6 @@ # Continuous Integration and Automation -Every change on the K3s repository, either made through a pull request or direct push, triggers the continuous integration pipelines defined within the same repository. Needless to say, all the K3s contributions can be merged until all the checks pass (AKA having green builds). +Every change on the OpenIM repository, either made through a pull request or direct push, triggers the continuous integration pipelines defined within the same repository. Needless to say, all the OpenIM contributions can be merged until all the checks pass (AKA having green builds). - [Continuous Integration and Automation](#continuous-integration-and-automation) - [CI Platforms](#ci-platforms) @@ -80,13 +80,15 @@ linux_mips64le darwin_amd64 windows_amd64 linux_amd64 linux_arm64". V Set to 1 enable verbose build. Default is 0. 📝 ``` + + How to Use Makefile to Help Contributors Build Projects Quickly 😊 The `make help` command is a handy tool that provides useful information on how to utilize the Makefile effectively. By running this command, contributors will gain insights into various targets and options available for building projects swiftly. Here's a breakdown of the targets and options provided by the Makefile: -Targets 😃 +**Targets 😃** 1. `all`: This target runs multiple tasks like `tidy`, `gen`, `add-copyright`, `format`, `lint`, `cover`, and `build`. It ensures comprehensive project building. 2. `build`: The primary target that compiles binaries by default. It is particularly useful for creating the necessary executable files. @@ -117,7 +119,7 @@ Targets 😃 27. `help`: Displays information about available targets and options. 28. `help-all`: Shows detailed information about all available targets and options. -Options 😄 +**Options 😄** 1. `DEBUG`: A boolean option that determines whether or not to generate debug symbols. The default value is 0 (false). 2. `BINS`: Specifies the binaries to build. By default, it builds all binaries under the `cmd` directory. Contributors can provide a list of specific binaries using this option. diff --git a/docs/contrib/development.md b/docs/contrib/development.md new file mode 100644 index 000000000..64aa08cda --- /dev/null +++ b/docs/contrib/development.md @@ -0,0 +1,80 @@ +# Development Guide + +Since OpenIM is written in Go, it is fair to assume that the Go tools are all one needs to contribute to this project. Unfortunately, there is a point where this no longer holds true when required to test or build local changes. This document elaborates on the required tooling for OpenIM development. + +- [Development Guide](#development-guide) + - [Non-Linux environment prerequisites](#non-linux-environment-prerequisites) + - [Windows Setup](#windows-setup) + - [macOS Setup](#macos-setup) + - [Installing Required Software](#installing-required-software) + - [Go](#go) + - [Docker](#docker) + - [Vagrant](#vagrant) + - [Cloning, Building and Testing OpenIM](#cloning-building-and-testing-openim) + - [Dependency management](#dependency-management) + +## Non-Linux environment prerequisites + +All the test and build scripts within this repository were created to be run on GNU Linux development environments. Due to this, it is suggested to use the virtual machine defined on this repository's [Vagrantfile](../../Vagrantfile) to use them. + +Either way, if one still wants to build and test OpenIM on non-Linux environments, specific setups are to be followed. + +### Windows Setup + +To build OpenIM on Windows is only possible for versions that support Windows Subsystem for Linux (WSL). If the development environment in question has Windows 10, Version 2004, Build 19041 or higher, [follow these instructions to install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10); otherwise, use a Linux Virtual machine instead. + +### macOS Setup + +The shell scripts in charge of the build and test processes rely on GNU utils (i.e. `sed`), [which slightly differ on macOS](https://unix.stackexchange.com/a/79357), meaning that one must make some adjustments before using them. + +First, install the GNU utils: + +```sh +brew install coreutils findutils gawk gnu-sed gnu-tar grep make +``` + +Then update the shell init script (i.e. `.bashrc`) to prepend the GNU Utils to the `$PATH` variable + +```sh +GNUBINS="$(find /usr/local/opt -type d -follow -name gnubin -print)" + +for bindir in ${GNUBINS[@]}; do + PATH=$bindir:$PATH +done + +export PATH +``` + +## Installing Required Software + +### Go + +It is well known that OpenIM is written in [Go](http://golang.org). Please follow the [Go Getting Started guide](https://golang.org/doc/install) to install and set up the Go tools used to compile and run the test batteries. + +| OpenIM | requires Go | +|----------------|-------------| +| 2.24 - 3.00 | 1.15 + | +| 3.30 + | 1.18 + | + +### Docker + +OpenIM build and test processes development require Docker to run certain steps. [Follow the Docker website instructions to install Docker](https://docs.docker.com/get-docker/) in the development environment. + +### Vagrant + +As described in the [Testing documentation](../../tests/TESTING.md), all the smoke tests are run in virtual machines managed by Vagrant. To install Vagrant in the development environment, [follow the instructions from the Hashicorp website](https://www.vagrantup.com/downloads), alongside any of the following hypervisors: + +- [VirtualBox](https://www.virtualbox.org/) +- [libvirt](https://libvirt.org/) and the [vagrant-libvirt plugin](https://github.com/vagrant-libvirt/vagrant-libvirt#installation) + +## Cloning, Building and Testing OpenIM + +These topics already have been addressed on their respective documents: + +- [Git Workflow](./git-workflow.md) +- [Building](../../BUILDING.md) +- [Testing](../../tests/TESTING.md) + +## Dependency management + +OpenIM uses [go modules](https://github.com/golang/go/wiki/Modules) to manage dependencies. diff --git a/docs/contrib/git_workflow.md b/docs/contrib/git_workflow.md new file mode 100644 index 000000000..1d21f9cdd --- /dev/null +++ b/docs/contrib/git_workflow.md @@ -0,0 +1,102 @@ +# Git workflows + +This document is an overview of OpenIM git workflow. It includes conventions, tips, and how to maintain good repository hygiene. + +- [Git workflows](#git-workflows) + - [Branching model](#branching-model) + - [Branch naming conventions](#branch-naming-conventions) + - [Backport policy](#backport-policy) + - [Git operations](#git-operations) + - [Setting up](#setting-up) + - [Branching out](#branching-out) + - [Keeping local branches in sync](#keeping-local-branches-in-sync) + - [Pushing changes](#pushing-changes) + +## Branching model + +OpenIM project uses the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) as its branching model, where most of the changes come from repositories forks instead of branches within the same one. + +### Branch naming conventions + +Every forked repository works independently, meaning that any contributor can create branches with the name they see fit. However, it is worth noting that OpenIM mirrors [OpenIM version skew policy](https://github.com/OpenIMSDK/Open-IM-Server/releases) by maintaining release branches for the most recent three minor releases. The only exception is that the main branch mirrors the latest OpenIM release (3.10) instead of using a `release-` prefixed one. + +```text +main -------------------------------------------. (OpenIM 3.10) +release-3.0.0 \---------------|---------------. (OpenIM 3.00) +release-2.4.0 \---------------. (OpenIM 2.40) +``` + + +### Backport policy + +All new work happens on the main branch, which means that for most cases, one should branch out from there and create the pull request against it. If the change involves adding a feature or patching OpenIM, the maintainers will backport it into the supported release branches. + +## Git operations + +There are everyday tasks related to git that every contributor needs to perform, and this section elaborates on them. + +### Setting up + +Creating a OpenIM fork, cloning it, and setting its upstream remote can be summarized on: + +1. Visit +2. Click the `Fork` button (top right) to establish a cloud-based fork +3. Clone fork to local storage +4. Add to your fork OpenIM remote as upstream + +Once cloned, in code it would look this way: + +```sh +## Clone fork to local storage +export user="your github profile name" +git clone https://github.com/$user/OpenIM.git +# or: git clone git@github.com:$user/OpenIM.git + +## Add OpenIM as upstream to your fork +cd OpenIM +git remote add upstream https://github.com/OpenIMSDK/Open-IM-Server.git +# or: git remote add upstream git@github.com:OpenIMSDK/Open-IM-Server.git + +## Ensure to never push to upstream directly +git remote set-url --push upstream no_push + +## Confirm that your remotes make sense: +git remote -v +``` + +### Branching out + +Every time one wants to work on a new OpenIM feature, we do: + +1. Get local main branch up to date +2. Create a new branch from the main one (i.e.: myfeature branch ) + +In code it would look this way: + +```sh +## Get local main up to date +# Assuming the OpenIM clone is the current working directory +git fetch upstream +git checkout main +git rebase upstream/main + +## Create a new branch from main +git checkout -b myfeature +``` + +### Keeping local branches in sync + +Either when branching out from main or a release one, keep in mind it is worth checking if any change has been pushed upstream by doing: + +```sh +git fetch upstream +git rebase upstream/main +``` + +It is suggested to `fetch` then `rebase` instead of `pull` since the latter does a merge, which leaves merge commits. For this, one can consider changing the local repository configuration by doing `git config branch.autoSetupRebase always` to change the behavior of `git pull`, or another non-merge option such as `git pull --rebase`. + +### Pushing changes + +For commit messages and signatures please refer to the [CONTRIBUTING.md](../../CONTRIBUTING.md) document. + +Nobody should push directly to upstream, even if one has such contributor access; instead, prefer [Github's pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) mechanism to contribute back into OpenIM. For expectations and guidelines about pull requests, consult the [CONTRIBUTING.md](../../CONTRIBUTING.md) document.