From 01271dac7b9b103b75b1c2ae56c7ba293500892d Mon Sep 17 00:00:00 2001 From: "Xinwei Xiong(cubxxw-openim)" <3293172751nss@gmail.com> Date: Mon, 4 Sep 2023 10:51:04 +0800 Subject: [PATCH] docs: fix docs link error issus:#968 Signed-off-by: Xinwei Xiong(cubxxw-openim) <3293172751nss@gmail.com> --- README-zh_CN.md | 2 +- README.md | 2 +- docs/README.md | 67 +++++++ docs/contrib/code_conventions.md | 2 +- docs/contrib/development.md | 12 +- docs/contrib/git_cherry-pick.md | 5 +- docs/conversions/github-workflow.md | 284 ++++++++++++++++++++++++++++ test/{README.md => readme} | 0 tools/ncpu/README.md | 8 - 9 files changed, 358 insertions(+), 24 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/conversions/github-workflow.md rename test/{README.md => readme} (100%) diff --git a/README-zh_CN.md b/README-zh_CN.md index a896f7381..951112ae4 100644 --- a/README-zh_CN.md +++ b/README-zh_CN.md @@ -324,7 +324,7 @@ OpenIM 我们的目标是建立一个顶级的开源社区。我们有一套标 - [提交标准](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/commit.md) - [版本控制标准](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/version.md) - [接口标准](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/api.md) -- [日志标准](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/log.md) +- [日志标准](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/) - [错误代码标准](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/error_code.md) ## :busts_in_silhouette: 社区 diff --git a/README.md b/README.md index c2a90e476..e326e6486 100644 --- a/README.md +++ b/README.md @@ -349,7 +349,7 @@ Before you start, please make sure your changes are in demand. The best for that - [Commit Standards](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/commit.md) - [Versioning Standards](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/version.md) - [Interface Standards](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/api.md) -- [Log Standards](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/log.md) +- [Log Standards](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/logging.md) - [Error Code Standards](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/error_code.md) ## :busts_in_silhouette: Community diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..e1d8c5d58 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,67 @@ +# OpenIM Server Docs + +Welcome to the OpenIM Documentation hub! This center provides a comprehensive range of guides and manuals designed to help you get the most out of your OpenIM experience. + +## Table of Contents + +1. [Contrib](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib) - Guidance on contributing and configurations for developers +2. [Conversions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions) - Coding conventions, logging policies, and other transformation tools + +------ + +## Contrib + +This section offers developers a detailed guide on how to contribute code, set up their environment, and follow the associated processes. + +- [Code Conventions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/code_conventions.md) - Rules and conventions for writing code in OpenIM. +- [Development Guide](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/development.md) - A guide on how to carry out development within OpenIM. +- [Git Cherry Pick](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/git_cherry-pick.md) - Guidelines on cherry-picking operations. +- [Git Workflow](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/git_workflow.md) - The git workflow in OpenIM. +- [Initialization Configurations](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/init_config.md) - Guidance on setting up and initializing OpenIM. +- [Docker Installation](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/install_docker.md) - How to install Docker on your machine. +- [Linux Development Environment](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/linux_development.md) - Guide to set up the development environment on Linux. +- [Local Actions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/local_actions.md) - Guidelines on how to carry out certain common actions locally. +- [Offline Deployment](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/offline-deployment.md) - Methods of deploying OpenIM offline. +- [Protoc Tools](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/protoc_tools.md) - Guide on using protoc tools. +- [Go Tools](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/util_go.md) - Tools and libraries in OpenIM for Go. +- [Makefile Tools](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/util_makefile.md) - Best practices and tools for Makefile. +- [Script Tools](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/util_scripts.md) - Best practices and tools for scripts. + +## Conversions + +This section introduces various conventions and policies within OpenIM, encompassing code, logs, versions, and more. + +- [API Conversions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/api.md) - Guidelines and methods for API conversions. +- [Logging Policy](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/bash_log.md) - Logging policies and conventions in OpenIM. +- [CI/CD Actions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/cicd_actions.md) - Procedures and conventions for CI/CD. +- [Commit Conventions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/commit.md) - Conventions for code commits in OpenIM. +- [Directory Conventions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/directory.md) - Directory structure and conventions within OpenIM. +- [Error Codes](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/error_code.md) - List and descriptions of error codes. +- [Go Code Conversions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/go_code.md) - Conventions and conversions for Go code. +- [Docker Image Strategy](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/images.md) - Management strategies for OpenIM Docker images, spanning multiple architectures and image repositories. +- [Logging Conventions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/logging.md) - Further detailed conventions on logging. +- [Version Conventions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/version.md) - Naming and management strategies for OpenIM versions. + + +## For Developers, Contributors, and Community Maintainers + +### Developers & Contributors + +If you're a developer or someone keen on contributing: + +- Familiarize yourself with our [Code Conventions](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/code_conventions.md) and [Git Workflow](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/git_workflow.md) to ensure smooth contributions. +- Dive into the [Development Guide](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/development.md) to get a hang of the development practices in OpenIM. + +### Community Maintainers + +As a community maintainer: + +- Ensure that contributions align with the standards outlined in our documentation. +- Regularly review the [Logging Policy](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/bash_log.md) and [Error Codes](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/error_code.md) to stay updated. + +## For Users + +Users should pay particular attention to: + +- [Docker Installation](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/install_docker.md) - Necessary if you're planning to use Docker images of OpenIM. +- [Docker Image Strategy](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/conversions/images.md) - To understand the different images available and how to choose the right one for your architecture. \ No newline at end of file diff --git a/docs/contrib/code_conventions.md b/docs/contrib/code_conventions.md index 1387da2f7..94478e6ff 100644 --- a/docs/contrib/code_conventions.md +++ b/docs/contrib/code_conventions.md @@ -35,4 +35,4 @@ ## Testing conventions -Please refer to [TESTING.md](../../tests/TESTING.md) document. +Please refer to [TESTING.md](https://github.com/OpenIMSDK/Open-IM-Server/tree/main/test/readme) document. diff --git a/docs/contrib/development.md b/docs/contrib/development.md index 64aa08cda..a8c640570 100644 --- a/docs/contrib/development.md +++ b/docs/contrib/development.md @@ -10,12 +10,11 @@ Since OpenIM is written in Go, it is fair to assume that the Go tools are all on - [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. +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](https://developer.hashicorp.com/vagrant/docs/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. @@ -62,18 +61,11 @@ OpenIM build and test processes development require Docker to run certain steps. ### 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: +As described in the [Testing documentation](https://github.com/OpenIMSDK/Open-IM-Server/tree/main/test/readme), 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 diff --git a/docs/contrib/git_cherry-pick.md b/docs/contrib/git_cherry-pick.md index ffa02eda2..9afb9c232 100644 --- a/docs/contrib/git_cherry-pick.md +++ b/docs/contrib/git_cherry-pick.md @@ -75,15 +75,14 @@ It is critical that our full community is actively engaged on enhancements in th - Be aware the cherry pick script assumes you have a git remote called `upstream` that points at the openim-server github org. - Please see our [recommended Git workflow](https://github.com/openim-server/community/blob/main/contributors/guide/github-workflow.md#workflow). + Please see our [recommended Git workflow](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contributors/github-workflow.md#workflow). - - You will need to run the cherry pick script separately for each patch release you want to cherry pick to. Cherry picks should be applied to all [active](https://github.com/openim-server/website/blob/main/content/en/releases/patch-releases.md#detailed-release-history-for-active-branches) release branches where the fix is applicable. + - You will need to run the cherry pick script separately for each patch release you want to cherry pick to. Cherry picks should be applied to all [active](https://github.com/OpenIMSDK/Open-IM-Server/releases) release branches where the fix is applicable. - If `GITHUB_TOKEN` is not set you will be asked for your github password: provide the github [personal access token](https://github.com/settings/tokens) rather than your actual github password. If you can securely set the environment variable `GITHUB_TOKEN` to your personal access token then you can avoid an interactive prompt. Refer [mislav/hub#2655 (comment)](https://github.com/mislav/hub/issues/2655#issuecomment-735836048) - Your cherry pick PR will immediately get the `do-not-merge/cherry-pick-not-approved` label. - [Normal rules apply for code merge](https://github.com/openim-server/community/blob/main/contributors/devel/sig-release/release.md#tldr), with some additional caveats outlined in the next section of this document. ## Cherry Pick Review diff --git a/docs/conversions/github-workflow.md b/docs/conversions/github-workflow.md new file mode 100644 index 000000000..013495e5e --- /dev/null +++ b/docs/conversions/github-workflow.md @@ -0,0 +1,284 @@ +--- +title: "GitHub Workflow" +weight: 6 +description: | + This document is an overview of the GitHub workflow used by the + open-im-server project. It includes tips and suggestions on keeping your + local environment in sync with upstream and how to maintain good + commit hygiene. +--- + +![Git workflow](git_workflow.png) + +## 1. Fork in the cloud + +1. Visit https://github.com/openimsdk/open-im-server +2. Click `Fork` button (top right) to establish a cloud-based fork. + +## 2. Clone fork to local storage + +Per Go's [workspace instructions][go-workspace], place open-im-server' code on your +`GOPATH` using the following cloning procedure. + +[go-workspace]: https://golang.org/doc/code.html#Workspaces + +In your shell, define a local working directory as `working_dir`. If your `GOPATH` has multiple paths, pick +just one and use it instead of `$GOPATH`. You must follow exactly this pattern, +neither `$GOPATH/src/github.com/${your github profile name}/` +nor any other pattern will work. + +```sh +export working_dir="$(go env GOPATH)/src/k8s.io" +``` + +If you already do Go development on github, the `k8s.io` directory +will be a sibling to your existing `github.com` directory. + +Set `user` to match your github profile name: + +```sh +export user= +``` + +Both `$working_dir` and `$user` are mentioned in the figure above. + +Create your clone: + +```sh +mkdir -p $working_dir +cd $working_dir +git clone https://github.com/$user/open-im-server.git +# or: git clone git@github.com:$user/open-im-server.git + +cd $working_dir/open-im-server +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 + +# Never push to upstream master +git remote set-url --push upstream no_push + +# Confirm that your remotes make sense: +git remote -v +``` + +## 3. Create a Working Branch + +Get your local master up to date. Note that depending on which repository you are working from, +the default branch may be called "main" instead of "master". + +```sh +cd $working_dir/open-im-server +git fetch upstream +git checkout master +git rebase upstream/master +``` + +Create your new branch. + +```sh +git checkout -b myfeature +``` + +You may now edit files on the `myfeature` branch. + +### Building open-im-server + +This workflow is process-specific. For quick-start build instructions for [openimsdk/open-im-server](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/util_makefile.md) + +## 4. Keep your branch in sync + +You will need to periodically fetch changes from the `upstream` +repository to keep your working branch in sync. Note that depending on which repository you are working from, +the default branch may be called 'main' instead of 'master'. + +Make sure your local repository is on your working branch and run the +following commands to keep it in sync: + +```sh +git fetch upstream +git rebase upstream/master +``` + +Please don't use `git pull` instead of the above `fetch` and +`rebase`. Since `git pull` executes a merge, it creates merge commits. These make the commit history messy +and violate the principle that commits ought to be individually understandable +and useful (see below). + +You might also consider changing your `.git/config` file via +`git config branch.autoSetupRebase always` to change the behavior of `git pull`, or another non-merge option such as `git pull --rebase`. + +## 5. Commit Your Changes + +You will probably want to regularly commit your changes. It is likely that you will go back and edit, +build, and test multiple times. After a few cycles of this, you might +[amend your previous commit](https://www.w3schools.com/git/git_amend.asp). + +```sh +git commit +``` + +## 6. Push to GitHub + +When your changes are ready for review, push your working branch to +your fork on GitHub. + +```sh +git push -f myfeature +``` + +## 7. Create a Pull Request + +1. Visit your fork at `https://github.com//open-im-server` +2. Click the **Compare & Pull Request** button next to your `myfeature` branch. +3. Check out the pull request process for more details and + advice. + +_If you have upstream write access_, please refrain from using the GitHub UI for +creating PRs, because GitHub will create the PR branch inside the main +repository rather than inside your fork. + +### Get a code review + +Once your pull request has been opened it will be assigned to one or more +reviewers. Those reviewers will do a thorough code review, looking for +correctness, bugs, opportunities for improvement, documentation and comments, +and style. + +Commit changes made in response to review comments to the same branch on your +fork. + +Very small PRs are easy to review. Very large PRs are very difficult to review. + +### Squash commits + +After a review, prepare your PR for merging by squashing your commits. + +All commits left on your branch after a review should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process. + +Before merging a PR, squash the following kinds of commits: + +- Fixes/review feedback +- Typos +- Merges and rebases +- Work in progress + +Aim to have every commit in a PR compile and pass tests independently if you can, but it's not a requirement. In particular, `merge` commits must be removed, as they will not pass tests. + +To squash your commits, perform an [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History): + +1. Check your git branch: + + ``` + git status + ``` + + The output should be similar to this: + + ``` + On branch your-contribution + Your branch is up to date with 'origin/your-contribution'. + ``` + +2. Start an interactive rebase using a specific commit hash, or count backwards from your last commit using `HEAD~`, where `` represents the number of commits to include in the rebase. + + ``` + git rebase -i HEAD~3 + ``` + + The output should be similar to this: + + ``` + pick 2ebe926 Original commit + pick 31f33e9 Address feedback + pick b0315fe Second unit of work + + # Rebase 7c34fc9..b0315ff onto 7c34fc9 (3 commands) + # + # Commands: + # p, pick = use commit + # r, reword = use commit, but edit the commit message + # e, edit = use commit, but stop for amending + # s, squash = use commit, but meld into previous commit + # f, fixup = like "squash", but discard this commit's log message + + ... + + ``` + +3. Use a command line text editor to change the word `pick` to `squash` for the commits you want to squash, then save your changes and continue the rebase: + + ``` + pick 2ebe926 Original commit + squash 31f33e9 Address feedback + pick b0315fe Second unit of work + + ... + + ``` + + The output after saving changes should look similar to this: + + ``` + [detached HEAD 61fdded] Second unit of work + Date: Thu Mar 5 19:01:32 2020 +0100 + 2 files changed, 15 insertions(+), 1 deletion(-) + + ... + + Successfully rebased and updated refs/heads/master. + ``` +4. Force push your changes to your remote branch: + + ``` + git push --force + ``` + +For mass automated fixups such as automated doc formatting, use one or more +commits for the changes to tooling and a final commit to apply the fixup en +masse. This makes reviews easier. + +An alternative to this manual squashing process is to use the Prow and Tide based automation that is configured in GitHub: adding a comment to your PR with `/label tide/merge-method-squash` will trigger the automation so that GitHub squash your commits onto the target branch once the PR is approved. Using this approach simplifies things for those less familiar with Git, but there are situations in where it's better to squash locally; reviewers will have this in mind and can ask for manual squashing to be done. + +By squashing locally, you control the commit message(s) for your work, and can separate a large PR into logically separate changes. +For example: you have a pull request that is code complete and has 24 commits. You rebase this against the same merge base, simplifying the change to two commits. Each of those two commits represents a single logical change and each commit message summarizes what changes. Reviewers see that the set of changes are now understandable, and approve your PR. + +## Merging a commit + +Once you've received review and approval, your commits are squashed, your PR is ready for merging. + +Merging happens automatically after both a Reviewer and Approver have approved the PR. If you haven't squashed your commits, they may ask you to do so before approving a PR. + +## Reverting a commit + +In case you wish to revert a commit, use the following instructions. + +_If you have upstream write access_, please refrain from using the +`Revert` button in the GitHub UI for creating the PR, because GitHub +will create the PR branch inside the main repository rather than inside your fork. + +- Create a branch and sync it with upstream. Note that depending on which repository you are working from, the default branch may be called 'main' instead of 'master'. + ```sh + # create a branch + git checkout -b myrevert + + # sync the branch with upstream + git fetch upstream + git rebase upstream/master + ``` +- If the commit you wish to revert is a *merge commit*, use this command: + ```sh + # SHA is the hash of the merge commit you wish to revert + git revert -m 1 + ``` + If it is a *single commit*, use this command: + ```sh + # SHA is the hash of the single commit you wish to revert + git revert + ``` + +- This will create a new commit reverting the changes. Push this new commit to your remote. + ```sh + git push myrevert + ``` + +- Finally, [create a Pull Request](#7-create-a-pull-request) using this branch. \ No newline at end of file diff --git a/test/README.md b/test/readme similarity index 100% rename from test/README.md rename to test/readme diff --git a/tools/ncpu/README.md b/tools/ncpu/README.md index 7edda5328..f7c05d583 100644 --- a/tools/ncpu/README.md +++ b/tools/ncpu/README.md @@ -37,11 +37,3 @@ The above command will ensure the build process takes advantage of all the avail ## Installation (Include installation steps here, e.g., how to clone the repo, build the tool, or install via package manager.) - -## Contributing - -If you have any suggestions, bug reports, or wish to contribute to the development of `ncpu`, please refer to our contribution guidelines (link to guidelines). - -## License - -`ncpu` is released under the [LICENSE_NAME](LINK_TO_LICENSE). Please refer to the license file for more details. \ No newline at end of file