diff --git a/.github/.codecov.yml b/.github/.codecov.yml index 45e213180..9e262e0e3 100644 --- a/.github/.codecov.yml +++ b/.github/.codecov.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + coverage: status: project: diff --git a/.github/labels.yml b/.github/labels.yml index 037790523..b85a824b4 100644 --- a/.github/labels.yml +++ b/.github/labels.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + # Refer to Kubernetes for size/* Settings # https://github.com/Kubernetes/Kubernetes XS: diff --git a/.github/sync.yml b/.github/sync.yml index 4e9f9d17e..413e5fcc7 100644 --- a/.github/sync.yml +++ b/.github/sync.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + # https://github.com/BetaHuhn/repo-file-sync-action # Synchronization for the.github repository OpenIMSDK/.github: diff --git a/.github/weekly-digest.yml b/.github/weekly-digest.yml index 9deb72e7b..fb3614ad8 100644 --- a/.github/weekly-digest.yml +++ b/.github/weekly-digest.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + # https://github.com/apps/weekly-digest/installations/new publishDay: sun canPublishIssues: true diff --git a/.github/workflows/auto-assign-issue.yml b/.github/workflows/auto-assign-issue.yml index 06fee28a1..d87a571dc 100644 --- a/.github/workflows/auto-assign-issue.yml +++ b/.github/workflows/auto-assign-issue.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Assign issue to comment author on: issue_comment: diff --git a/.github/workflows/auto-gh-pr.yml b/.github/workflows/auto-gh-pr.yml index efa77ee29..1d8c90d33 100644 --- a/.github/workflows/auto-gh-pr.yml +++ b/.github/workflows/auto-gh-pr.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Auto PR to release on: @@ -5,16 +19,10 @@ on: # types: # - closed -env: - GH_TOKEN: ${{ secrets.REDBOT_GITHUB_TOKEN }} - ISSUE: ${{ github.event.issue.html_url }} - OWNER: ${{ github.repository_owner }} - REPO: ${{ github.event.repository.name }} - jobs: create-pr: runs-on: ubuntu-latest - if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main' + if: github.event.pull_request.base.ref == 'main' steps: - name: Check out code uses: actions/checkout@v3 @@ -29,14 +37,14 @@ jobs: sudo apt-get install gh continue-on-error: true - - name: Configure GitHub CLI - run: | - git config --global user.email "3293172751ysy@gmail.com" - git config --global user.name "kubbot" - echo "${{ secrets.BOT_GITHUB_TOKEN }}" | gh auth login --with-token + # - name: Configure GitHub CLI + # run: | + # git config --global user.email "3293172751ysy@gmail.com" + # git config --global user.name "kubbot" + # echo "${{ secrets.BOT_GITHUB_TOKEN }}" | gh auth login --with-token - name: Create PR to release branch run: | - ISSUEID=$(gh pr view 642 --repo $OWNER/$REPO | grep -oP 'Fixes #\K\d+') + ISSUEID=$(gh pr view ${{ github.event.pull_request.number }} --repo $OWNER/$REPO | grep -oP 'Fixes #\K\d+') echo "===========> $ISSUEID" ISSUE=$(gh issue view $ISSUEID --repo $OWNER/$REPO --json labels,assignees,milestone,title) echo "===========> $ISSUE" @@ -46,12 +54,17 @@ jobs: MILESTONE=$(echo $ISSUE | jq -r '.milestone | select(.title) | .title') TITLE=$(echo $ISSUE | jq -r '.title') - echo $ISSUE | jq - gh pr edit ${{ github.event.pull_request.number }} --repo $OWNER/$REPO --add-label "$LABELS" --add-assignee "$ASSIGNEES" --milestone "$MILESTONE" git checkout -b bot/merge-to-release-$ISSUEID git push origin bot/merge-to-release-$ISSUEID gh pr create --base release --head bot/merge-to-release-$ISSUEID --title "Merge main to release" --body "" - # gh pr create --base main --head feat/auto-release-pr-624 --title "The bug is fixed" --body "$x" --repo OpenIMSDK/Open-IM-Server --reviewer "cubxxw" \ No newline at end of file + # gh pr create --base main --head feat/auto-release-pr-624 --title "The bug is fixed" --body "$x" --repo OpenIMSDK/Open-IM-Server --reviewer "cubxxw" + continue-on-error: true + env: + GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }} + GH_TOKEN: ${{ github.token }} + ISSUE: ${{ github.event.issue.html_url }} + OWNER: ${{ github.repository_owner }} + REPO: ${{ github.event.repository.name }} \ No newline at end of file diff --git a/.github/workflows/auto-invite.yml b/.github/workflows/auto-invite.yml index 9d8effb51..2bc644bfb 100644 --- a/.github/workflows/auto-invite.yml +++ b/.github/workflows/auto-invite.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Invite users to join our group on: issue_comment: diff --git a/.github/workflows/bot-auto-cherry-pick.yml b/.github/workflows/bot-auto-cherry-pick.yml index 4cb2cf0ec..0d545813a 100644 --- a/.github/workflows/bot-auto-cherry-pick.yml +++ b/.github/workflows/bot-auto-cherry-pick.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: 'Github Rebot for Cherry Pick when PR is merged' on: pull_request_target: diff --git a/.github/workflows/bot-cherry-pick.yml b/.github/workflows/bot-cherry-pick.yml index 9b5ff49bb..59a4979cf 100644 --- a/.github/workflows/bot-cherry-pick.yml +++ b/.github/workflows/bot-cherry-pick.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Github Rebot for Cherry Pick On Comment on: issue_comment: diff --git a/.github/workflows/build-docker-image.yml b/.github/workflows/build-docker-image.yml index 31e0a5b65..ff58d8d8f 100644 --- a/.github/workflows/build-docker-image.yml +++ b/.github/workflows/build-docker-image.yml @@ -12,38 +12,99 @@ # See the License for the specific language governing permissions and # limitations under the License. -name: OpenIM Build Docker Images +name: Publish Docker image + on: push: + branches: + - main tags: - v* + workflow_dispatch: + jobs: build: runs-on: ubuntu-latest - strategy: - matrix: - bin: - - openim-server steps: - - name: Checkout + - name: Check out the repo uses: actions/checkout@v3 - - name: Setup Docker Buildx - uses: docker/setup-buildx-action@v2 - - name: Login to GitHub Container Registry - uses: docker/login-action@v2 + + - name: Log in to Docker Hub + uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9 with: - registry: ghcr.io - username: ${{ github.repository_owner }} - password: ${{ secrets.GITHUB_TOKEN }} - - name: Docker metadata - id: metadata - uses: docker/metadata-action@v4 + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + + - name: Extract metadata (tags, labels) for Docker + id: meta + uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38 with: - images: ghcr.io/${{ github.repository_owner }}/openim-${{ matrix.bin }} - - name: Build and release Docker images - uses: docker/build-push-action@v3 + images: openim/openim-server + tags: latest + + - name: Build and push Docker image + uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc with: - platforms: linux/386,linux/amd64,linux/arm64/v8 - target: ${{ matrix.bin }} - tags: ${{ steps.metadata.outputs.tags }} - push: true \ No newline at end of file + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + + + - name: Log in to AliYun Docker Hub + uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9 + with: + registry: registry.cn-hangzhou.aliyuncs.com + username: ${{ secrets.ALIREGISTRY_USERNAME }} + password: ${{ secrets.ALIREGISTRY_TOKEN }} + + - name: Extract metadata (tags, labels) for Docker + id: meta2 + uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38 + with: + images: registry.cn-hangzhou.aliyuncs.com/openimsdk/openim-server + tags: latest + + - name: Build and push Docker image + uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc + with: + context: . + push: true + tags: ${{ steps.meta2.outputs.tags }} + labels: ${{ steps.meta2.outputs.labels }} + +# name: OpenIM Build Docker Images +# on: +# push: +# tags: +# - v* +# jobs: +# build: +# runs-on: ubuntu-latest +# strategy: +# matrix: +# bin: +# - openim-server +# steps: +# - name: Checkout +# uses: actions/checkout@v3 +# - name: Setup Docker Buildx +# uses: docker/setup-buildx-action@v2 +# - name: Login to GitHub Container Registry +# uses: docker/login-action@v2 +# with: +# registry: ghcr.io +# username: ${{ github.repository_owner }} +# password: ${{ secrets.GITHUB_TOKEN }} +# - name: Docker metadata +# id: metadata +# uses: docker/metadata-action@v4 +# with: +# images: ghcr.io/${{ github.repository_owner }}/openim-${{ matrix.bin }} +# - name: Build and release Docker images +# uses: docker/build-push-action@v3 +# with: +# platforms: linux/386,linux/amd64,linux/arm64/v8 +# target: ${{ matrix.bin }} +# tags: ${{ steps.metadata.outputs.tags }} +# push: true \ No newline at end of file diff --git a/.github/workflows/check-coverage.yml b/.github/workflows/check-coverage.yml index cc596a0e0..937af89d6 100644 --- a/.github/workflows/check-coverage.yml +++ b/.github/workflows/check-coverage.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Check-Coverage on: diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml index 603a49399..3f658284a 100644 --- a/.github/workflows/cla.yml +++ b/.github/workflows/cla.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: "OpenIM CLA Assistant" on: issue_comment: diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 6233ffcad..a76979ab9 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -13,7 +13,7 @@ # limitations under the License. -name: "Code Scanning - Action" +name: "OpenIM Code Scanning - Action" on: push: @@ -42,8 +42,8 @@ jobs: security-events: write # only required for workflows in private repositories - actions: read - contents: read + actions: write + contents: write steps: - name: Checkout repository @@ -53,8 +53,8 @@ jobs: - name: Initialize CodeQL uses: github/codeql-action/init@v2 # Override language selection by uncommenting this and choosing your languages - # with: - # languages: go, javascript, csharp, python, cpp, java, ruby + with: + languages: go # Autobuild attempts to build any compiled languages (C/C++, C#, Go, or Java). # If this step fails, then you should remove it and run the build manually (see below). @@ -68,9 +68,9 @@ jobs: # three lines and modify them (or add more) to build your code if your # project uses a compiled language - #- run: | - # make bootstrap - # make release + # - run: | + # make bootstrap + # make release - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v2 \ No newline at end of file diff --git a/.github/workflows/create_branch_on_tag.yml b/.github/workflows/create_branch_on_tag.yml new file mode 100644 index 000000000..bdb53e80a --- /dev/null +++ b/.github/workflows/create_branch_on_tag.yml @@ -0,0 +1,62 @@ +name: Create Branch on Tag + +on: + push: + tags: + - 'v*.*.0' + +jobs: + create-branch: + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Set up Git + run: | + git config --global user.name 'kubbot' + git config --global user.email '3293172751yxy@gmail.com' + + - name: Install git-chglog + run: make install.git-chglog + + - name: Create Branch + run: | + TAG_NAME=${GITHUB_REF/refs\/tags\//} + IFS='.' read -ra VERSION_PARTS <<< "$TAG_NAME" + if [[ "${VERSION_PARTS[2]}" = "0" ]]; then + BRANCH_NAME="release-v${VERSION_PARTS[0]}.${VERSION_PARTS[1]}" + echo "Creating branch $BRANCH_NAME" + git checkout -b "$BRANCH_NAME" + git push origin "$BRANCH_NAME" + fi + + - name: Push Changes + uses: stefanzweifel/git-auto-commit-action@v4 + with: + commit_message: "Auto Commit CHANGELOG" + branch: release-v${VERSION_PARTS[0]}.${VERSION_PARTS[1]} + env: + GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }} + + - name: Create and Push CHANGELOG + run: | + git checkout main + TAG_NAME=${GITHUB_REF/refs\/tags\//} + IFS='.' read -ra VERSION_PARTS <<< "$TAG_NAME" + if [[ "${VERSION_PARTS[2]}" = "0" ]]; then + cd CHANGELOG + git-chglog --tag-filter-pattern "v${VERSION_PARTS[0]}.${VERSION_PARTS[1]}.*" -o "CHANGELOG-${VERSION_PARTS[0]}.${VERSION_PARTS[1]}.md" + git add "CHANGELOG-${VERSION_PARTS[0]}.${VERSION_PARTS[1]}.md" + git commit -m "Update CHANGELOG for $TAG_NAME" + fi + + - name: Push Changes + uses: stefanzweifel/git-auto-commit-action@v4 + with: + commit_message: "Auto Commit CHANGELOG" + branch: main + env: + GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }} \ No newline at end of file diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 3fbad1e5f..ef50743a1 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: deploy for dev on: diff --git a/.github/workflows/e2e-test.yml b/.github/workflows/e2e-test.yml index a3451d6aa..b9fa29aef 100644 --- a/.github/workflows/e2e-test.yml +++ b/.github/workflows/e2e-test.yml @@ -1,2 +1,16 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + # name: OpenIM e2e Test diff --git a/.github/workflows/gosec.yml b/.github/workflows/gosec.yml index 43fba5c0c..708eca4f8 100644 --- a/.github/workflows/gosec.yml +++ b/.github/workflows/gosec.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: OpenIM Run Gosec # gosec is a source code security audit tool for the Go language. It performs a static diff --git a/.github/workflows/help-comment-issue.yml b/.github/workflows/help-comment-issue.yml index 5f52e638f..755fb035d 100644 --- a/.github/workflows/help-comment-issue.yml +++ b/.github/workflows/help-comment-issue.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Good frist issue add comment on: issues: diff --git a/.github/workflows/issue-robot.yml b/.github/workflows/issue-robot.yml index 74927a0c2..b421a5314 100644 --- a/.github/workflows/issue-robot.yml +++ b/.github/workflows/issue-robot.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: 'issue translator' on: issue_comment: diff --git a/.github/workflows/link-pr.yml b/.github/workflows/link-pr.yml index c6da4cb5f..07b9d46a9 100644 --- a/.github/workflows/link-pr.yml +++ b/.github/workflows/link-pr.yml @@ -1,12 +1,23 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Github Rebot for Link check error # Every Monday at 12:30 p.m on: schedule: - cron: '30 12 * * 1' - push: - branches: - - main jobs: linkChecker: diff --git a/.github/workflows/lock-issue.yml b/.github/workflows/lock-issue.yml index 8cf0433d6..6a9aed9ba 100644 --- a/.github/workflows/lock-issue.yml +++ b/.github/workflows/lock-issue.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM open source community. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: 'Lock Threads' on: diff --git a/.github/workflows/opencommit.yml b/.github/workflows/opencommit.yml index 69f7d7f23..36307c00f 100644 --- a/.github/workflows/opencommit.yml +++ b/.github/workflows/opencommit.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: 'OpenIM Commit Action' on: diff --git a/.github/workflows/openimci.yml b/.github/workflows/openimci.yml index cd055b5b7..07133126b 100644 --- a/.github/workflows/openimci.yml +++ b/.github/workflows/openimci.yml @@ -128,6 +128,14 @@ jobs: # commit_author: Kubbot # defaults to author of the commit that triggered the run continue-on-error: true + - name: Commit Changes + uses: stefanzweifel/git-auto-commit-action@v4 + with: + commit_message: "chore(fmt): robot automated format and lint Change" + commit_options: '--no-verify --signoff' + branch: main + continue-on-error: true + - name: Set Current Directory id: set_directory run: | diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 726d57e14..3405e479e 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -1,11 +1,24 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: Github Pull Request on: push: branches: [main] paths-ignore: - 'README.md' - - 'CONTRIBUTING.md' - + - 'CONTRIBUTING.md' - 'docs/**' pull_request: branches: [main] @@ -22,18 +35,80 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - name: checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Get League branch Patch + run: | + git config user.name 'openimbot' + git config user.email 'openimsdk@qq.com' + git checkout -b cicd/patch-${{ github.event.number }} - uses: actions/setup-node@v3 + - name: Setup Go + uses: actions/setup-go@v2 + - name: Run go modules tidy + run: | + sudo make tidy + sudo make tools.verify.go-gitlint + echo "Run go modules tidy successfully" + + - name: Run go format + run: | + sudo make format + echo "Run go format successfully" + continue-on-error: true + + - name: Generate all necessary files, such as error code files + run: | + make generate + echo "Generate all necessary files successfully" + continue-on-error: true + + - name: Run unit test and get test coverage + run: | + make cover + echo "Run unit test and get test coverage successfully" + continue-on-error: true + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: go + + - name: Build source code for host platform + run: | + sudo make build + echo "Build source code for host platform successfully" + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + + - name: OpenIM verify copyright + run: | + sudo make verify-copyright + sudo make add-copyright + echo "OpenIM verify successfully" + continue-on-error: true + + - name: Commit code + run: | + git add . + - name: Create Pull Request uses: peter-evans/create-pull-request@v5 with: - token: ${{ secrets.BOT_GITHUB_TOKEN }} - commit-message: 'build: update distribution' - title: 'build: update distribution' + commit-message: "cicd: bump League Patch to cicd/patch-${{ github.event.number }}" + title: Bump League Patch to cicd/patch-${{ github.event.number }} body: | - - Updates the distribution for changes on `main` - - Auto-generated by [create-pull-request][1] - - [1]: https://github.com/OpenIMSDK/Open-IM-Sever - branch: 'bot/update-distribution' \ No newline at end of file + Review criteria: + + - [ ] Disenchanter can connect and issue actions + + This is an automated PR. + [workflow](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/.github/workflows/pull-request.yml). + base: main + branch: cicd/patch-${{ github.event.number }} + labels: kind/documentation, area/test, ok-to-test + token: ${{ secrets.REDBOT_GITHUB_TOKEN }} \ No newline at end of file diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c4f190766..45ed79df2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: OpenIM Server Release on: diff --git a/.github/workflows/scripts-test.yml b/.github/workflows/scripts-test.yml index badb33012..e59e696f8 100644 --- a/.github/workflows/scripts-test.yml +++ b/.github/workflows/scripts-test.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + name: OpenIM Start Execute Scripts on: diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 2cad62c85..7790aa944 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -1,3 +1,17 @@ +# Copyright © 2023 OpenIM. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + # This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time. # # You can adjust the behavior by modifying this file. diff --git a/.goreleaser.yaml b/.goreleaser.yaml index f9ca78474..cbb9ba483 100644 --- a/.goreleaser.yaml +++ b/.goreleaser.yaml @@ -36,8 +36,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-cmdutils id: openim-cmdutils main: ./cmd/openim-cmdutils/main.go @@ -53,8 +54,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-crontask id: openim-crontask main: ./cmd/openim-crontask/main.go @@ -70,8 +72,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-msggateway id: openim-msggateway main: ./cmd/openim-msggateway/main.go @@ -87,8 +90,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-msgtransfer id: openim-msgtransfer main: ./cmd/openim-msgtransfer/main.go @@ -104,8 +108,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-push id: openim-push main: ./cmd/openim-push/main.go @@ -121,8 +126,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-auth id: openim-rpc-auth main: ./cmd/openim-rpc/openim-rpc-auth/main.go @@ -138,8 +144,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-conversation id: openim-rpc-conversation main: ./cmd/openim-rpc/openim-rpc-conversation/main.go @@ -155,8 +162,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-friend id: openim-rpc-friend main: ./cmd/openim-rpc/openim-rpc-friend/main.go @@ -172,8 +180,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-group id: openim-rpc-group main: ./cmd/openim-rpc/openim-rpc-group/main.go @@ -189,8 +198,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-msg id: openim-rpc-msg main: ./cmd/openim-rpc/openim-rpc-msg/main.go @@ -206,8 +216,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-third id: openim-rpc-third main: ./cmd/openim-rpc/openim-rpc-third/main.go @@ -223,8 +234,9 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" + - binary: openim-rpc-user id: openim-rpc-user main: ./cmd/openim-rpc/openim-rpc-user/main.go @@ -240,8 +252,8 @@ builds: - ppc64le - arm64 goarm: - - 6 - - 7 + - "6" + - "7" archives: - format: tar.gz @@ -323,6 +335,66 @@ changelog: - title: Other work order: 9999 +dockers: + - image_templates: + - "openimsdk/open-im-server:{{ .Tag }}-amd64" + - "ghcr.io/goreleaser/goreleaser:{{ .Tag }}-amd64" + dockerfile: Dockerfile + use: buildx + build_flag_templates: + - "--pull" + - "--label=io.artifacthub.package.readme-url=https://raw.githubusercontent.com/goreleaser/goreleaser/main/README.md" + - "--label=io.artifacthub.package.logo-url=https://goreleaser.com/static/avatar.png" + - '--label=io.artifacthub.package.maintainers=[{"name":"Carlos Alexandro Becker","email":"carlos@carlosbecker.dev"}]' + - "--label=io.artifacthub.package.license=MIT" + - "--label=org.opencontainers.image.description=Deliver Go binaries as fast and easily as possible" + - "--label=org.opencontainers.image.created={{.Date}}" + - "--label=org.opencontainers.image.name={{.ProjectName}}" + - "--label=org.opencontainers.image.revision={{.FullCommit}}" + - "--label=org.opencontainers.image.version={{.Version}}" + - "--label=org.opencontainers.image.source={{.GitURL}}" + - "--platform=linux/amd64" + extra_files: + - scripts/entrypoint.sh + - image_templates: + - "goreleaser/goreleaser:{{ .Tag }}-arm64" + - "ghcr.io/goreleaser/goreleaser:{{ .Tag }}-arm64" + dockerfile: Dockerfile + use: buildx + build_flag_templates: + - "--pull" + - "--label=io.artifacthub.package.readme-url=https://raw.githubusercontent.com/goreleaser/goreleaser/main/README.md" + - "--label=io.artifacthub.package.logo-url=https://goreleaser.com/static/avatar.png" + - '--label=io.artifacthub.package.maintainers=[{"name":"Carlos Alexandro Becker","email":"carlos@carlosbecker.dev"}]' + - "--label=io.artifacthub.package.license=MIT" + - "--label=org.opencontainers.image.description=Deliver Go binaries as fast and easily as possible" + - "--label=org.opencontainers.image.created={{.Date}}" + - "--label=org.opencontainers.image.name={{.ProjectName}}" + - "--label=org.opencontainers.image.revision={{.FullCommit}}" + - "--label=org.opencontainers.image.version={{.Version}}" + - "--label=org.opencontainers.image.source={{.GitURL}}" + - "--platform=linux/arm64" + goarch: arm64 + extra_files: + - scripts/entrypoint.sh + +docker_manifests: + - name_template: "goreleaser/goreleaser:{{ .Tag }}" + image_templates: + - "goreleaser/goreleaser:{{ .Tag }}-amd64" + - "goreleaser/goreleaser:{{ .Tag }}-arm64" + - name_template: "ghcr.io/goreleaser/goreleaser:{{ .Tag }}" + image_templates: + - "ghcr.io/goreleaser/goreleaser:{{ .Tag }}-amd64" + - "ghcr.io/goreleaser/goreleaser:{{ .Tag }}-arm64" + - name_template: "goreleaser/goreleaser:latest" + image_templates: + - "goreleaser/goreleaser:{{ .Tag }}-amd64" + - "goreleaser/goreleaser:{{ .Tag }}-arm64" + - name_template: "ghcr.io/goreleaser/goreleaser:latest" + image_templates: + - "ghcr.io/goreleaser/goreleaser:{{ .Tag }}-amd64" + - "ghcr.io/goreleaser/goreleaser:{{ .Tag }}-arm64" nfpms: - id: packages @@ -412,19 +484,22 @@ release: ## Helping out + We release logs are recorded on [✨ CHANGELOG](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/CHANGELOG/CHANGELOG.md) + This release is only possible thanks to **all** the support of some **awesome people**! - Want to be one of them? + **Want to be one of them 😘?** + Contributions to this project are welcome! Please see [CONTRIBUTING.md](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/CONTRIBUTING.md) for details.
diff --git a/CHANGELOG/CHANGELOG.md b/CHANGELOG/CHANGELOG.md index 2d788d4c4..822e9bc92 100644 --- a/CHANGELOG/CHANGELOG.md +++ b/CHANGELOG/CHANGELOG.md @@ -1,6 +1,7 @@ # Changelog - [Changelog](#changelog) + - [OpenIM versioning policy](#openim-versioning-policy) - [command](#command) - [create next tag](#create-next-tag) - [Release version logs](#release-version-logs) @@ -15,6 +16,10 @@ All notable changes to this project will be documented in this file. + [https://github.com/OpenIMSDK/Open-IM-Server/releases](https://github.com/OpenIMSDK/Open-IM-Server/releases) +## OpenIM versioning policy + ++ [OpenIM Version](../docs/conversions/version.md) + ## command ```bash diff --git a/README.md b/README.md index c4a4318b2..11471ac0f 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ DATA_DIR=./ #designate large disk directory 1. Deploy and start -Note: This command can only be executed once. It will modify the component passwords in docker-compose based on the PASSWORD variable in .env, and modify the component passwords in config/config.yaml. If the password in .env changes, you need to first execute docker-compose down; rm components -rf and then execute this command. +> **Note**: This command can only be executed once. It will modify the component passwords in docker-compose based on the PASSWORD variable in .env, and modify the component passwords in config/config.yaml. If the password in .env changes, you need to first execute docker-compose down; rm components -rf and then execute this command. ``` chmod +x install_im_server.sh; diff --git a/build/docker/openim-api/Dockerfile b/build/docker/openim-api/Dockerfile new file mode 100644 index 000000000..1bf965ea4 --- /dev/null +++ b/build/docker/openim-api/Dockerfile @@ -0,0 +1,12 @@ +FROM golang:1.20.0 as build + +WORKDIR /openim + +RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \ + echo "Asia/Shanghai" > /etc/timezone && \ + mkdir -p /var/log/miniblog + +COPY miniblog /openim + +EXPOSE 10002 +CMD ["./bin/openim-api","--port", "10002"] \ No newline at end of file diff --git a/build/docker/openim-cmdutils/Dockerfile b/build/docker/openim-cmdutils/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-crontask/Dockerfile b/build/docker/openim-crontask/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-msggateway/Dockerfile b/build/docker/openim-msggateway/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-msgtransfer/Dockerfile b/build/docker/openim-msgtransfer/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-push/Dockerfile b/build/docker/openim-push/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-auth/Dockerfile b/build/docker/openim-rpc-auth/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-conversation/Dockerfile b/build/docker/openim-rpc-conversation/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-friend/Dockerfile b/build/docker/openim-rpc-friend/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-group/Dockerfile b/build/docker/openim-rpc-group/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-msg/Dockerfile b/build/docker/openim-rpc-msg/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-third/Dockerfile b/build/docker/openim-rpc-third/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/build/docker/openim-rpc-user/Dockerfile b/build/docker/openim-rpc-user/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/config/config.yaml b/config/config.yaml index 10d43bd3e..1c01031dc 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -24,8 +24,8 @@ zookeeper: mysql: address: [ 127.0.0.1:13306 ] #目前仅支持单机 - username: root - password: openIM123 + username: root #用户名 + password: openIM123 #密码 database: openIM_v3 #不建议修改 maxOpenConn: 1000 #最大连接数 maxIdleConn: 100 #最大空闲连接数 @@ -37,14 +37,14 @@ mongo: uri: #不为空则直接使用该值 address: [ 127.0.0.1:37017 ] #单机时为mongo地址,使用分片集群时,为mongos地址 database: openIM_v3 #mongo db 默认即可 - username: root - password: openIM123 + username: root #用户名 + password: openIM123 #密码 maxPoolSize: 100 redis: address: [ 127.0.0.1:16379 ] # username: #only redis version 6.0+ need username - password: openIM123 + password: openIM123 #密码 kafka: username: #用户名 @@ -77,9 +77,9 @@ object: apiURL: "http://127.0.0.1:10002/object/" #地址需要app能访问到 minio: bucket: "openim" #不建议修改 - endpoint: http://127.0.0.1:10005 #地址需要app能够访问 - accessKeyID: root - secretAccessKey: openIM123 + endpoint: "http://127.0.0.1:10005" #minio对外服务的ip和端口,app要能访问此ip和端口 + accessKeyID: "root" #ID + secretAccessKey: "openIM123" #秘钥 sessionToken: "" #token cos: #tencent cos bucketURL: "https://temp-1252357374.cos.ap-chengdu.myqcloud.com" @@ -167,7 +167,7 @@ retainChatRecords: 365 #mongo保存离线消息 chatRecordsClearTime: "0 2 * * 3" #每周三凌晨2点清理mongo中的过期(超过retainChatRecords时间)消息,这个删除是为了清理满足上个配置retainChatRecords的过期消息,不会发送通知,仅仅作为清理磁盘使用 msgDestructTime: "0 2 * * *" #消息自动删除时间,每天凌晨2点删除过期消息,这个删除是为了删除保留时间超过超过会话字段msg_destruct_time(秒)的消息。 -secret: openIM123 +secret: tuoyun #秘钥,获取token时校验 tokenPolicy: expire: 90 #过期时间(天) diff --git a/docs/conversions/README.md b/docs/conversions/README.md new file mode 100644 index 000000000..05fd7dcb1 --- /dev/null +++ b/docs/conversions/README.md @@ -0,0 +1,9 @@ +## OpenIM Project Development Standards + +- [Code Standards](https://chat.openai.com/go_code.md) +- [Directory Standards](https://chat.openai.com/directory.md) +- [Commit Standards](https://chat.openai.com/commit.md) +- [Versioning Standards](https://chat.openai.com/version.md) +- [Interface Standards](https://chat.openai.com/api.md) +- [Log Standards](https://chat.openai.com/log.md) +- [Error Code Standards](https://chat.openai.com/error_code.md) \ No newline at end of file diff --git a/docs/conversions/api.md b/docs/conversions/api.md new file mode 100644 index 000000000..1dd389258 --- /dev/null +++ b/docs/conversions/api.md @@ -0,0 +1,5 @@ +## Interface Standards + +Our project, OpenIM, adheres to the [OpenAPI 3.0](https://spec.openapis.org/oas/latest.html) interface standards. + +> Chinese translation: [OpenAPI Specification Chinese Translation](https://fishead.gitbook.io/openapi-specification-zhcn-translation/3.0.0.zhcn) \ No newline at end of file diff --git a/docs/conversions/commit.md b/docs/conversions/commit.md new file mode 100644 index 000000000..661661fe9 --- /dev/null +++ b/docs/conversions/commit.md @@ -0,0 +1,9 @@ +## Commit Standards + +Our project, OpenIM, follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) standards. + +> Chinese translation: [Conventional Commits: A Specification Making Commit Logs More Human and Machine-friendly](https://tool.lu/en_US/article/2ac/preview) + +In addition to adhering to these standards, we encourage all contributors to the OpenIM project to ensure that their commit messages are clear and descriptive. This helps in maintaining a clean and meaningful project history. Each commit message should succinctly describe the changes made and, where necessary, the reasoning behind those changes. + +To facilitate a streamlined process, we also recommend using appropriate commit type based on Conventional Commits guidelines such as `fix:` for bug fixes, `feat:` for new features, and so forth. Understanding and using these conventions helps in generating automatic release notes, making versioning easier, and improving overall readability of commit history. \ No newline at end of file diff --git a/docs/conversions/directory.md b/docs/conversions/directory.md new file mode 100644 index 000000000..4e30d3854 --- /dev/null +++ b/docs/conversions/directory.md @@ -0,0 +1,3 @@ +## Catalog Service Interface Specification + ++ [https://github.com/kubecub/go-project-layout](https://github.com/kubecub/go-project-layout) \ No newline at end of file diff --git a/docs/conversions/error_code.md b/docs/conversions/error_code.md new file mode 100644 index 000000000..169567b33 --- /dev/null +++ b/docs/conversions/error_code.md @@ -0,0 +1,22 @@ +## Error Code Standards + +Error codes are one of the important means for users to locate and solve problems. When an application encounters an exception, users can quickly locate and resolve the problem based on the error code and the description and solution of the error code in the documentation. + +### Error Code Naming Standards + +- Follow CamelCase notation; +- Error codes are divided into two levels. For example, `InvalidParameter.BindError`, separated by a `.`. The first-level error code is platform-level, and the second-level error code is resource-level, which can be customized according to the scenario; +- The second-level error code can only use English letters or numbers ([a-zA-Z0-9]), and should use standard English word spelling, standard abbreviations, RFC term abbreviations, etc.; +- The error code should avoid multiple definitions of the same semantics, for example: `InvalidParameter.ErrorBind`, `InvalidParameter.BindError`. + +### First-Level Common Error Codes + +| Error Code | Error Description | Error Type | +| ---------------- | ------------------------------------------------------------ | ---------- | +| InternalError | Internal error | 1 | +| InvalidParameter | Parameter error (including errors in parameter type, format, value, etc.) | 0 | +| AuthFailure | Authentication / Authorization error | 0 | +| ResourceNotFound | Resource does not exist | 0 | +| FailedOperation | Operation failed | 2 | + +> Error Type: 0 represents the client, 1 represents the server, 2 represents both the client / server. \ No newline at end of file diff --git a/docs/conversions/go_code.md b/docs/conversions/go_code.md new file mode 100644 index 000000000..85d099f9c --- /dev/null +++ b/docs/conversions/go_code.md @@ -0,0 +1,901 @@ +## Go 代码开发规范 +在Go 项目开发中,一个好的编码规范可以极大的提高代码质量。为了帮你节省时间和精力,这里我整理了一份清晰、可直接套用的 Go 编码规范,供你参考。 + +这份规范,是我参考了 Go 官方提供的编码规范,以及 Go 社区沉淀的一些比较合理的规范之后,加入自己的理解总结出的,它比很多公司内部的规范更全面,你掌握了,以后在面试大厂的时候,或者在大厂里写代码的时候,都会让人高看你一眼,觉得你code很专业。 + +这份编码规范中包含代码风格、命名规范、注释规范、类型、控制结构、函数、GOPATH 设置规范、依赖管理和最佳实践九类规范。如果你觉得这些规范内容太多了,看完一遍也记不住,这完全没关系。你可以多看几遍,也可以在用到时把它翻出来,在实际应用中掌握。这篇特别放送的内容,更多是作为写代码时候的一个参考手册。 + +## 1. 代码风格 + +### 1.1 代码格式 + +- 代码都必须用 `gofmt` 进行格式化。 +- 运算符和操作数之间要留空格。 +- 建议一行代码不超过120个字符,超过部分,请采用合适的换行方式换行。但也有些例外场景,例如import行、工具自动生成的代码、带tag的struct字段。 +- 文件长度不能超过800行。 +- 函数长度不能超过80行。 +- import规范 + - 代码都必须用`goimports`进行格式化(建议将代码Go代码编辑器设置为:保存时运行 `goimports`)。 + - 不要使用相对路径引入包,例如 `import ../util/net` 。 + - 包名称与导入路径的最后一个目录名不匹配时,或者多个相同包名冲突时,则必须使用导入别名。 + +```go + // bad + "github.com/dgrijalva/jwt-go/v4" + + //good + jwt "github.com/dgrijalva/jwt-go/v4" +``` + - 导入的包建议进行分组,匿名包的引用使用一个新的分组,并对匿名包引用进行说明。 + +```go + import ( + // go 标准包 + "fmt" + + // 第三方包 + "github.com/jinzhu/gorm" + "github.com/spf13/cobra" + "github.com/spf13/viper" + + // 匿名包单独分组,并对匿名包引用进行说明 + // import mysql driver + _ "github.com/jinzhu/gorm/dialects/mysql" + + // 内部包 + v1 "github.com/marmotedu/api/apiserver/v1" + metav1 "github.com/marmotedu/apimachinery/pkg/meta/v1" + "github.com/marmotedu/iam/pkg/cli/genericclioptions" + ) +``` + +### 1.2 声明、初始化和定义 + +当函数中需要使用到多个变量时,可以在函数开始处使用`var`声明。在函数外部声明必须使用 `var` ,不要采用 `:=` ,容易踩到变量的作用域的问题。 + +```go +var ( + Width int + Height int +) +``` + +- 在初始化结构引用时,请使用`&T{}`代替`new(T)`,以使其与结构体初始化一致。 + +```go +// bad +sptr := new(T) +sptr.Name = "bar" + +// good +sptr := &T{Name: "bar"} +``` + +- struct 声明和初始化格式采用多行,定义如下。 + +```go +type User struct{ + Username string + Email string +} + +user := User{ + Username: "belm", + Email: "nosbelm@qq.com", +} +``` + +- 相似的声明放在一组,同样适用于常量、变量和类型声明。 + +```go +// bad +import "a" +import "b" + +// good +import ( + "a" + "b" +) +``` + +- 尽可能指定容器容量,以便为容器预先分配内存,例如: + +```go +v := make(map[int]string, 4) +v := make([]string, 0, 4) +``` + +- 在顶层,使用标准var关键字。请勿指定类型,除非它与表达式的类型不同。 + +```go +// bad +var _s string = F() + +func F() string { return "A" } + +// good +var _s = F() +// 由于 F 已经明确了返回一个字符串类型,因此我们没有必要显式指定_s 的类型 +// 还是那种类型 + +func F() string { return "A" } +``` + +- 对于未导出的顶层常量和变量,使用`_`作为前缀。 + +```go +// bad +const ( + defaultHost = "127.0.0.1" + defaultPort = 8080 +) + +// good +const ( + _defaultHost = "127.0.0.1" + _defaultPort = 8080 +) +``` + +- 嵌入式类型(例如 mutex)应位于结构体内的字段列表的顶部,并且必须有一个空行将嵌入式字段与常规字段分隔开。 + +```go +// bad +type Client struct { + version int + http.Client +} + +// good +type Client struct { + http.Client + + version int +} +``` + +### 1.3 错误处理 + +- `error`作为函数的值返回,必须对`error`进行处理,或将返回值赋值给明确忽略。对于`defer xx.Close()`可以不用显式处理。 + +```go +func load() error { + // normal code +} + +// bad +load() + +// good + _ = load() +``` + +- `error`作为函数的值返回且有多个返回值的时候,`error`必须是最后一个参数。 + +```go +// bad +func load() (error, int) { + // normal code +} + +// good +func load() (int, error) { + // normal code +} +``` + +- 尽早进行错误处理,并尽早返回,减少嵌套。 + +```go +// bad +if err != nil { + // error code +} else { + // normal code +} + +// good +if err != nil { + // error handling + return err +} +// normal code +``` + +- 如果需要在 if 之外使用函数调用的结果,则应采用下面的方式。 + +```go +// bad +if v, err := foo(); err != nil { + // error handling +} + +// good +v, err := foo() +if err != nil { + // error handling +} +``` + +- 错误要单独判断,不与其他逻辑组合判断。 + +```go +// bad +v, err := foo() +if err != nil || v == nil { + // error handling + return err +} + +// good +v, err := foo() +if err != nil { + // error handling + return err +} + +if v == nil { + // error handling + return errors.New("invalid value v") +} +``` + +- 如果返回值需要初始化,则采用下面的方式。 + +```go +v, err := f() +if err != nil { + // error handling + return // or continue. +} +``` + +- 错误描述建议 + - 错误描述用小写字母开头,结尾不要加标点符号,例如: +```go + // bad + errors.New("Redis connection failed") + errors.New("redis connection failed.") + + // good + errors.New("redis connection failed") +``` + - 告诉用户他们可以做什么,而不是告诉他们不能做什么。 + - 当声明一个需求时,用must 而不是should。例如,`must be greater than 0、must match regex '[a-z]+'`。 + - 当声明一个格式不对时,用must not。例如,`must not contain`。 + - 当声明一个动作时用may not。例如,`may not be specified when otherField is empty、only name may be specified`。 + - 引用文字字符串值时,请在单引号中指示文字。例如,`ust not contain '..'`。 + - 当引用另一个字段名称时,请在反引号中指定该名称。例如,must be greater than `request`。 + - 指定不等时,请使用单词而不是符号。例如,`must be less than 256、must be greater than or equal to 0 (不要用 larger than、bigger than、more than、higher than)`。 + - 指定数字范围时,请尽可能使用包含范围。 + - 建议 Go 1.13 以上,error 生成方式为 `fmt.Errorf("module xxx: %w", err)`。 + +### 1.4 panic处理 + +- 在业务逻辑处理中禁止使用panic。 +- 在main包中,只有当程序完全不可运行时使用panic,例如无法打开文件、无法连接数据库导致程序无法正常运行。 +- 在main包中,使用 `log.Fatal` 来记录错误,这样就可以由log来结束程序,或者将panic抛出的异常记录到日志文件中,方便排查问题。 +- 可导出的接口一定不能有panic。 +- 包内建议采用error而不是panic来传递错误。 + +### 1.5 单元测试 + +- 单元测试文件名命名规范为 `example_test.go`。 +- 每个重要的可导出函数都要编写测试用例。 +- 因为单元测试文件内的函数都是不对外的,所以可导出的结构体、函数等可以不带注释。 +- 如果存在 `func (b *Bar) Foo` ,单测函数可以为 `func TestBar_Foo`。 + +### 1.6 类型断言失败处理 + +- type assertion 的单个返回值针对不正确的类型将产生 panic。请始终使用 “comma ok”的惯用法。 + +```go +// bad +t := n.(int) + +// good +t, ok := n.(int) +if !ok { + // error handling +} +``` + +## 2. 命名规范 + +命名规范是代码规范中非常重要的一部分,一个统一的、短小的、精确的命名规范可以大大提高代码的可读性,也可以借此规避一些不必要的Bug。 + +### 2.1 包命名 + +- 包名必须和目录名一致,尽量采取有意义、简短的包名,不要和标准库冲突。 +- 包名全部小写,没有大写或下划线,使用多级目录来划分层级。 +- 项目名可以通过中划线来连接多个单词。 +- 包名以及包所在的目录名,不要使用复数,例如,是`net/url`,而不是`net/urls`。 +- 不要用 common、util、shared 或者 lib 这类宽泛的、无意义的包名。 +- 包名要简单明了,例如 net、time、log。 + +### 2.2 函数命名 + +- 函数名采用驼峰式,首字母根据访问控制决定使用大写或小写,例如:`MixedCaps`或者`mixedCaps`。 +- 代码生成工具自动生成的代码(如`xxxx.pb.go`)和为了对相关测试用例进行分组,而采用的下划线(如`TestMyFunction_WhatIsBeingTested`)排除此规则。 + +### 2.3 文件命名 + +- 文件名要简短有意义。 +- 文件名应小写,并使用下划线分割单词。 + +### 2.4 结构体命名 + +- 采用驼峰命名方式,首字母根据访问控制决定使用大写或小写,例如`MixedCaps`或者`mixedCaps`。 +- 结构体名不应该是动词,应该是名词,比如 `Node`、`NodeSpec`。 +- 避免使用Data、Info这类无意义的结构体名。 +- 结构体的声明和初始化应采用多行,例如: + +```go +// User 多行声明 +type User struct { + Name string + Email string +} + +// 多行初始化 +u := User{ + UserName: "belm", + Email: "nosbelm@qq.com", +} +``` + +### 2.5 接口命名 + +- 接口命名的规则,基本和结构体命名规则保持一致: + - 单个函数的接口名以 “er"”作为后缀(例如Reader,Writer),有时候可能导致蹩脚的英文,但是没关系。 + - 两个函数的接口名以两个函数名命名,例如ReadWriter。 + - 三个以上函数的接口名,类似于结构体名。 + +例如: + +``` + // Seeking to an offset before the start of the file is an error. + // Seeking to any positive offset is legal, but the behavior of subsequent + // I/O operations on the underlying object is implementation-dependent. + type Seeker interface { + Seek(offset int64, whence int) (int64, error) + } + + // ReadWriter is the interface that groups the basic Read and Write methods. + type ReadWriter interface { + Reader + Writer + } +``` + +### 2.6 变量命名 + +- 变量名必须遵循驼峰式,首字母根据访问控制决定使用大写或小写。 +- 在相对简单(对象数量少、针对性强)的环境中,可以将一些名称由完整单词简写为单个字母,例如: + - user 可以简写为 u; + - userID 可以简写 uid。 +- 特有名词时,需要遵循以下规则: + - 如果变量为私有,且特有名词为首个单词,则使用小写,如 apiClient。 + - 其他情况都应当使用该名词原有的写法,如 APIClient、repoID、UserID。 + +下面列举了一些常见的特有名词。 + +``` +// A GonicMapper that contains a list of common initialisms taken from golang/lint +var LintGonicMapper = GonicMapper{ + "API": true, + "ASCII": true, + "CPU": true, + "CSS": true, + "DNS": true, + "EOF": true, + "GUID": true, + "HTML": true, + "HTTP": true, + "HTTPS": true, + "ID": true, + "IP": true, + "JSON": true, + "LHS": true, + "QPS": true, + "RAM": true, + "RHS": true, + "RPC": true, + "SLA": true, + "SMTP": true, + "SSH": true, + "TLS": true, + "TTL": true, + "UI": true, + "UID": true, + "UUID": true, + "URI": true, + "URL": true, + "UTF8": true, + "VM": true, + "XML": true, + "XSRF": true, + "XSS": true, +} +``` + +- 若变量类型为bool类型,则名称应以Has,Is,Can或Allow开头,例如: + +```go +var hasConflict bool +var isExist bool +var canManage bool +var allowGitHook bool +``` + +- 局部变量应当尽可能短小,比如使用buf指代buffer,使用i指代index。 +- 代码生成工具自动生成的代码可排除此规则(如`xxx.pb.go`里面的Id) + +### 2.7 常量命名 + +- 常量名必须遵循驼峰式,首字母根据访问控制决定使用大写或小写。 +- 如果是枚举类型的常量,需要先创建相应类型: + +```go +// Code defines an error code type. +type Code int + +// Internal errors. +const ( + // ErrUnknown - 0: An unknown error occurred. + ErrUnknown Code = iota + // ErrFatal - 1: An fatal error occurred. + ErrFatal +) +``` + +### 2.8 Error的命名 + +- Error类型应该写成FooError的形式。 + +```go +type ExitError struct { + // .... +} +``` + +- Error变量写成ErrFoo的形式。 + +```go +var ErrFormat = errors.New("unknown format") +``` + +## 3. 注释规范 + +- 每个可导出的名字都要有注释,该注释对导出的变量、函数、结构体、接口等进行简要介绍。 +- 全部使用单行注释,禁止使用多行注释。 +- 和代码的规范一样,单行注释不要过长,禁止超过 120 字符,超过的请使用换行展示,尽量保持格式优雅。 +- 注释必须是完整的句子,以需要注释的内容作为开头,句点作为结尾,`格式为 // 名称 描述.`。例如: + +```go +// bad +// logs the flags in the flagset. +func PrintFlags(flags *pflag.FlagSet) { + // normal code +} + +// good +// PrintFlags logs the flags in the flagset. +func PrintFlags(flags *pflag.FlagSet) { + // normal code +} +``` + +- 所有注释掉的代码在提交code review前都应该被删除,否则应该说明为什么不删除,并给出后续处理建议。 + +- 在多段注释之间可以使用空行分隔加以区分,如下所示: + +```go +// Package superman implements methods for saving the world. +// +// Experience has shown that a small number of procedures can prove +// helpful when attempting to save the world. +package superman +``` + +### 3.1 包注释 + +- 每个包都有且仅有一个包级别的注释。 +- 包注释统一用 // 进行注释,格式为 `// Package 包名 包描述`,例如: + +```go +// Package genericclioptions contains flags which can be added to you command, bound, completed, and produce +// useful helper functions. +package genericclioptions +``` + +### 3.2 变量/常量注释 + +- 每个可导出的变量/常量都必须有注释说明,`格式为// 变量名 变量描述`,例如: + +```go +// ErrSigningMethod defines invalid signing method error. +var ErrSigningMethod = errors.New("Invalid signing method") +``` +- 出现大块常量或变量定义时,可在前面注释一个总的说明,然后在每一行常量的前一行或末尾详细注释该常量的定义,例如: +```go +// Code must start with 1xxxxx. +const ( + // ErrSuccess - 200: OK. + ErrSuccess int = iota + 100001 + + // ErrUnknown - 500: Internal server error. + ErrUnknown + + // ErrBind - 400: Error occurred while binding the request body to the struct. + ErrBind + + // ErrValidation - 400: Validation failed. + ErrValidation +) +``` +### 3.3 结构体注释 + +- 每个需要导出的结构体或者接口都必须有注释说明,格式为 `// 结构体名 结构体描述.`。 +- 结构体内的可导出成员变量名,如果意义不明确,必须要给出注释,放在成员变量的前一行或同一行的末尾。例如: + +```go +// User represents a user restful resource. It is also used as gorm model. +type User struct { + // Standard object's metadata. + metav1.ObjectMeta `json:"metadata,omitempty"` + + Nickname string `json:"nickname" gorm:"column:nickname"` + Password string `json:"password" gorm:"column:password"` + Email string `json:"email" gorm:"column:email"` + Phone string `json:"phone" gorm:"column:phone"` + IsAdmin int `json:"isAdmin,omitempty" gorm:"column:isAdmin"` +} +``` + +### 3.4 方法注释 + +每个需要导出的函数或者方法都必须有注释,格式为// 函数名 函数描述.,例如: + +```go +// BeforeUpdate run before update database record. +func (p *Policy) BeforeUpdate() (err error) { + // normal code + return nil +} +``` + +### 3.5 类型注释 + +- 每个需要导出的类型定义和类型别名都必须有注释说明,格式为 `// 类型名 类型描述.`,例如: + +```go +// Code defines an error code type. +type Code int +``` + +## 4. 类型 + +### 4.1 字符串 + +- 空字符串判断。 + +```go +// bad +if s == "" { + // normal code +} + +// good +if len(s) == 0 { + // normal code +} +``` + +- `[]byte`/`string`相等比较。 + +```go +// bad +var s1 []byte +var s2 []byte +... +bytes.Equal(s1, s2) == 0 +bytes.Equal(s1, s2) != 0 + +// good +var s1 []byte +var s2 []byte +... +bytes.Compare(s1, s2) == 0 +bytes.Compare(s1, s2) != 0 +``` + +- 复杂字符串使用raw字符串避免字符转义。 + +```go +// bad +regexp.MustCompile("\\.") + +// good +regexp.MustCompile(`\.`) +``` + +### 4.2 切片 + +- 空slice判断。 + +```go +// bad +if len(slice) = 0 { + // normal code +} + +// good +if slice != nil && len(slice) == 0 { + // normal code +} +``` + +上面判断同样适用于map、channel。 + +- 声明slice。 + +```go +// bad +s := []string{} +s := make([]string, 0) + +// good +var s []string +``` + +- slice复制。 + +```go +// bad +var b1, b2 []byte +for i, v := range b1 { + b2[i] = v +} +for i := range b1 { + b2[i] = b1[i] +} + +// good +copy(b2, b1) +``` + +- slice新增。 + +```go +// bad +var a, b []int +for _, v := range a { + b = append(b, v) +} + +// good +var a, b []int +b = append(b, a...) +``` + +### 4.3 结构体 + +- struct初始化。 + +struct以多行格式初始化。 + +```go +type user struct { + Id int64 + Name string +} + +u1 := user{100, "Colin"} + +u2 := user{ + Id: 200, + Name: "Lex", +} +``` + +## 5. 控制结构 + +### 5.1 if + +- if 接受初始化语句,约定如下方式建立局部变量。 + +```go +if err := loadConfig(); err != nil { + // error handling + return err +} +``` + +- if 对于bool类型的变量,应直接进行真假判断。 + +```go +var isAllow bool +if isAllow { + // normal code +} +``` + +### 5.2 for + +- 采用短声明建立局部变量。 + +```go +sum := 0 +for i := 0; i < 10; i++ { + sum += 1 +} +``` + +- 不要在 for 循环里面使用 defer,defer只有在函数退出时才会执行。 + +```go +// bad +for file := range files { + fd, err := os.Open(file) + if err != nil { + return err + } + defer fd.Close() + // normal code +} + +// good +for file := range files { + func() { + fd, err := os.Open(file) + if err != nil { + return err + } + defer fd.Close() + // normal code + }() +} +``` + +### 5.3 range + +- 如果只需要第一项(key),就丢弃第二个。 + +```go +for key := range keys { +// normal code +} +``` + +- 如果只需要第二项,则把第一项置为下划线。 + +```go +sum := 0 +for _, value := range array { + sum += value +} +``` + +### 5.4 switch + +- 必须要有default。 + +```go +switch os := runtime.GOOS; os { + case "linux": + fmt.Println("Linux.") + case "darwin": + fmt.Println("OS X.") + default: + fmt.Printf("%s.\n", os) +} +``` + +### 5.5 goto +- 业务代码禁止使用 goto 。 +- 框架或其他底层源码尽量不用。 + +## 6. 函数 + +- 传入变量和返回变量以小写字母开头。 +- 函数参数个数不能超过5个。 +- 函数分组与顺序 +- 函数应按粗略的调用顺序排序。 +- 同一文件中的函数应按接收者分组。 +- 尽量采用值传递,而非指针传递。 +- 传入参数是 map、slice、chan、interface ,不要传递指针。 + +### 6.1 函数参数 + +- 如果函数返回相同类型的两个或三个参数,或者如果从上下文中不清楚结果的含义,使用命名返回,其他情况不建议使用命名返回,例如: + +```go +func coordinate() (x, y float64, err error) { + // normal code +} +``` +- 传入变量和返回变量都以小写字母开头。 +- 尽量用值传递,非指针传递。 +- 参数数量均不能超过5个。 +- 多返回值最多返回三个,超过三个请使用 struct。 + +### 6.2 defer + +- 当存在资源创建时,应紧跟defer释放资源(可以大胆使用defer,defer在Go1.14版本中,性能大幅提升,defer的性能损耗即使在性能敏感型的业务中,也可以忽略)。 +- 先判断是否错误,再defer释放资源,例如: + +```go +rep, err := http.Get(url) +if err != nil { + return err +} + +defer resp.Body.Close() +``` + +### 6.3 方法的接收器 + +- 推荐以类名第一个英文首字母的小写作为接收器的命名。 +- 接收器的命名在函数超过20行的时候不要用单字符。 +- 接收器的命名不能采用me、this、self这类易混淆名称。 + +### 6.4 嵌套 +- 嵌套深度不能超过4层。 + +### 6.5 变量命名 +- 变量声明尽量放在变量第一次使用的前面,遵循就近原则。 +- 如果魔法数字出现超过两次,则禁止使用,改用一个常量代替,例如: + +```go +// PI ... +const Prise = 3.14 + +func getAppleCost(n float64) float64 { + return Prise * n +} + +func getOrangeCost(n float64) float64 { + return Prise * n +} +``` + +## 7. GOPATH 设置规范 +- Go 1.11 之后,弱化了 GOPATH 规则,已有代码(很多库肯定是在1.11之前建立的)肯定符合这个规则,建议保留 GOPATH 规则,便于维护代码。 +- 建议只使用一个 GOPATH,不建议使用多个 GOPATH。如果使用多个GOPATH,编译生效的 bin 目录是在第一个 GOPATH 下。 + +## 8. 依赖管理 + +- Go 1.11 以上必须使用 Go Modules。 +- 使用Go Modules作为依赖管理的项目时,不建议提交vendor目录。 +- 使用Go Modules作为依赖管理的项目时,必须提交go.sum文件。 + +### 9. 最佳实践 + +- 尽量少用全局变量,而是通过参数传递,使每个函数都是“无状态”的。这样可以减少耦合,也方便分工和单元测试。 +- 在编译时验证接口的符合性,例如: + +```go +type LogHandler struct { + h http.Handler + log *zap.Logger +} +var _ http.Handler = LogHandler{} +``` +- 服务器处理请求时,应该创建一个context,保存该请求的相关信息(如requestID),并在函数调用链中传递。 + +### 9.1 性能 +- string 表示的是不可变的字符串变量,对 string 的修改是比较重的操作,基本上都需要重新申请内存。所以,如果没有特殊需要,需要修改时多使用 []byte。 +- 优先使用 strconv 而不是 fmt。 + +### 9.2 注意事项 + +- append 要小心自动分配内存,append 返回的可能是新分配的地址。 +- 如果要直接修改 map 的 value 值,则 value 只能是指针,否则要覆盖原来的值。 +- map 在并发中需要加锁。 +- 编译过程无法检查 interface{} 的转换,只能在运行时检查,小心引起 panic。 + +## 总结 + +这里向你介绍了九类常用的编码规范。但今天的最后,我要在这里提醒你一句:规范是人定的,你也可以根据需要,制定符合你项目的规范,但同时我也建议你采纳这些业界沉淀下来的规范,并通过工具来确保规范的执行。 diff --git a/docs/conversions/logging.md b/docs/conversions/logging.md new file mode 100644 index 000000000..82f74c9aa --- /dev/null +++ b/docs/conversions/logging.md @@ -0,0 +1,20 @@ +## Log Standards + +### Log Standards + +- The unified log package `github.com/OpenIMSDK/Open-IM-Server/internal/pkg/log` should be used for all logging; +- Use structured logging formats: `log.Infow`, `log.Warnw`, `log.Errorw`, etc. For example: `log.Infow("Update post function called")`; +- All logs should start with an uppercase letter and should not end with a `.`. For example: `log.Infow("Update post function called")`; +- Use past tense. For example, use `Could not delete B` instead of `Cannot delete B`; +- Adhere to log level standards: + - Debug level logs use `log.Debugw`; + - Info level logs use `log.Infow`; + - Warning level logs use `log.Warnw`; + - Error level logs use `log.Errorw`; + - Panic level logs use `log.Panicw`; + - Fatal level logs use `log.Fatalw`. +- Log settings: + - Development and test environments: The log level is set to `debug`, the log format can be set to `console` / `json` as needed, and caller is enabled; + - Production environment: The log level is set to `info`, the log format is set to `json`, and caller is enabled. (**Note**: In the early stages of going online, to facilitate troubleshooting, the log level can be set to `debug`) +- When logging, avoid outputting sensitive information, such as passwords, keys, etc. +- If you are calling a logging function in a function/method with a `context.Context` parameter, it is recommended to use `log.L(ctx).Infow()` for logging. \ No newline at end of file diff --git a/docs/conversions/version.md b/docs/conversions/version.md new file mode 100644 index 000000000..a421dd549 --- /dev/null +++ b/docs/conversions/version.md @@ -0,0 +1,57 @@ +# OpenIM Branch Management and Versioning + +Our project, OpenIM, follows the [Semantic Versioning 2.0.0](https://semver.org/lang/zh-CN/) standards. + +## OpenIM version + +OpenIM manages two primary branches: `main` and `release`. The project uses Semantic Versioning 2.0.0 to tag different versions of the software, each indicating a significant milestone in the software's development. + +In the OpenIM repository, the versioning adheres to the `MAJOR.MINOR.PATCH` format, where: + +- `MAJOR` version changes when there are incompatible changes to the API, +- `MINOR` version changes when features are added in a backward-compatible manner, and +- `PATCH` version changes when backward-compatible bugs are fixed. + +## Milestones and Branching + +When a significant milestone like v3.1.0 is achieved, a new branch `release-v3.1` is created. This branch contains all the code pertaining to this stable release. All bug fixes and features intended for the next version, v3.2.0, are merged into this branch. + +The release of `PATCH` versions (Z in `X.Y.Z`) are driven by bug fixes, and these can be rolled out depending on the bug's priority or over a scheduled time. On the other hand, `MINOR` versions (Y in `X.Y.Z`) are released based on the project's roadmap, milestone completion, or on a scheduled timeline. Importantly, the API of minor versions is always backward-compatible. + +## Dealing with Major Bugs + +In the event of a major bug discovery, the fix would selectively be merged into the previous version (e.g., v3.1 or the `release-v3.1` branch), as well as into the `main` branch. This is to ensure that users relying on the older version can still receive important bug fixes, while also keeping the main branch updated. + +It's worth noting that a robust testing regime should be in place to ensure the integrity of all branches at any given time. Automated tests and code review sessions are crucial components of maintaining a healthy codebase. + +To summarize, OpenIM's approach to branch management and versioning ensures a balance between introducing new features, fixing bugs, and maintaining backward compatibility. This strategy is vital for managing user expectations, supporting older versions, and paving the way for the project's continuous growth. + +## Git Workflow Example + +To put the above principles into practice, here's a Git workflow example that you might follow when working on a bug fix: + +``` +bashCopy code# Checkout the branch for the version that needs the bug fix +git checkout release-v3.1 + +# Create a new branch for the bug fix +git checkout -b bug/bug-name + +# ... Make changes, commit your work ... + +# Push the branch to your remote repository +git push origin bug/bug-name + +# After the pull request is merged into the release-v3.1 branch, +# checkout and update your main branch +git checkout main +git pull origin main + +# Merge or rebase the changes from release-v3.1 into main +git merge release-v3.1 + +# Push the updates to the main branch +git push origin main +``` + +Remember, communication with your team is key throughout this process, keeping everyone up-to-date with the changes being made. \ No newline at end of file diff --git a/scripts/make-rules/common.mk b/scripts/make-rules/common.mk index d471ec112..93057fef5 100644 --- a/scripts/make-rules/common.mk +++ b/scripts/make-rules/common.mk @@ -60,6 +60,7 @@ endif ifeq ($(origin VERSION), undefined) # VERSION := $(shell git describe --abbrev=0 --dirty --always --tags | sed 's/-/./g') #v2.3.3.dirty +# git describe --tags --always --match="v*" --dirty VERSION := $(shell git describe --tags --always --match="v*" --dirty | sed 's/-/./g') #v2.3.3.631.g00abdc9b.dirty # v2.3.3: git tag endif @@ -110,13 +111,16 @@ else IMAGE_PLAT := $(PLATFORM) endif +# Protobuf file storage path +APIROOT=$(ROOT_DIR)/pkg/proto + # Linux command settings # TODO: Whether you need to join utils? -FIND := find . ! -path './utils/*' ! -path './vendor/*' -XARGS := xargs -r +FIND := find . ! -path './utils/*' ! -path './vendor/*' ! -path './third_party/*' +XARGS := xargs -r --no-run-if-empty # Linux command settings-CODE DIRS Copyright -CODE_DIRS := $(ROOT_DIR)/pkg $(ROOT_DIR)/cmd $(ROOT_DIR)/config $(ROOT_DIR)/db $(ROOT_DIR)/.docker-compose_cfg $(ROOT_DIR)/internal $(ROOT_DIR)/scripts $(ROOT_DIR)/test +CODE_DIRS := $(ROOT_DIR)/pkg $(ROOT_DIR)/cmd $(ROOT_DIR)/config $(ROOT_DIR)/db $(ROOT_DIR)/.docker-compose_cfg $(ROOT_DIR)/internal $(ROOT_DIR)/scripts $(ROOT_DIR)/test $(ROOT_DIR)/.github $(ROOT_DIR)/build $(ROOT_DIR)/build $(ROOT_DIR)/deployments FINDS := find $(CODE_DIRS) # Makefile settings: Select different behaviors by determining whether V option is set diff --git a/scripts/make-rules/golang.mk b/scripts/make-rules/golang.mk index cf07f0cda..282649d7e 100644 --- a/scripts/make-rules/golang.mk +++ b/scripts/make-rules/golang.mk @@ -173,9 +173,9 @@ go.test.cover: go.test.junit-report .PHONY: go.format go.format: tools.verify.golines tools.verify.goimports @echo "===========> Formating codes" - @$(FIND) -type f -name '*.go' | $(XARGS) gofmt -s -w - @$(FIND) -type f -name '*.go' | $(XARGS) $(TOOLS_DIR)/goimports -w -local $(ROOT_PACKAGE) - @$(FIND) -type f -name '*.go' | $(XARGS) $(TOOLS_DIR)/golines -w --max-len=200 --reformat-tags --shorten-comments --ignore-generated . + @$(FIND) -type f -name '*.go' -not -name '*pb*' | $(XARGS) gofmt -s -w + @$(FIND) -type f -name '*.go' -not -name '*pb*' | $(XARGS) $(TOOLS_DIR)/goimports -w -local $(ROOT_PACKAGE) + @$(FIND) -type f -name '*.go' -not -name '*pb*' | $(XARGS) $(TOOLS_DIR)/golines -w --max-len=200 --reformat-tags --shorten-comments --ignore-generated . @$(GO) mod edit -fmt ## imports: task to automatically handle import packages in Go files using goimports tool