add document for using git

docs/git_workflow.md

@@ -0,0 +1,83 @@
+When working with a Git repository and its fork, following best practices can help maintain a smooth workflow, keep your fork updated, and avoid common issues like merge conflicts. Here are some good practices:
+
+### 1. **Keep Your Fork Up-to-Date**
+
+- **Add an Upstream Remote**: After forking the repository, add the original repository as an upstream remote.
+  ```bash
+  git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
+  ```
+- **Regularly Fetch from Upstream**: Periodically fetch the changes from the upstream repository to keep your fork up-to-date.
+  ```bash
+  git fetch upstream
+  git checkout main
+  git merge upstream/main
+  ```
+- **Rebase Your Work**: Instead of merging, you can use rebase to apply your changes on top of the latest upstream commits, keeping your history cleaner.
+  ```bash
+  git pull --rebase upstream main
+  ```
+
+### 2. **Create Feature Branches**
+
+- Always create a new branch for each feature or bug fix you're working on. Never work directly on the `main` branch of your fork.
+  ```bash
+  git checkout -b feature-branch
+  ```
+- This helps to isolate work and makes it easier to manage pull requests and reviews.
+
+### 3. **Work in Small, Logical Commits**
+
+- Make frequent, small, and logical commits that represent single units of change. Use meaningful commit messages that explain the "why" of the change.
+  ```bash
+  git commit -m "Fix bug in user authentication"
+  ```
+
+### 4. **Use Pull Requests (PRs) for Collaboration**
+
+- When you’re ready to contribute changes back to the original repository, create a pull request (PR). Ensure your PR is well-documented and easy to review:
+  - Write a clear description of what changes you’re introducing.
+  - Reference any related issues.
+  - Use PR templates if available.
+
+### 5. **Sync Your Fork with the Upstream Before Opening a PR**
+
+- Before submitting a pull request, make sure your fork is up-to-date with the upstream repository:
+  ```bash
+  git fetch upstream
+  git checkout main
+  git merge upstream/main
+  ```
+- Resolve any conflicts and ensure that your feature branch is fully synced with the upstream.
+
+### 6. **Squash or Rebase Commits Before PRs (Optional)**
+
+- If your branch has many small, work-in-progress commits, consider squashing or rebasing them into a single commit for a cleaner history.
+  ```bash
+  git rebase -i main
+  ```
+- Squashing simplifies the history, making it easier for maintainers to review your changes.
+
+### 7. **Test Thoroughly**
+
+- Before pushing your changes or submitting a PR, ensure your changes are thoroughly tested. Run the test suite provided by the project, if available, and add new tests if applicable.
+  ```bash
+  git push origin feature-branch
+  ```
+
+### 8. **Handle Conflicts Properly**
+
+- If your feature branch diverges from the upstream and conflicts arise during merging or rebasing, resolve the conflicts carefully and re-run any tests to ensure nothing is broken.
+
+### 9. **Clean Up Old Branches**
+
+- Once a feature branch has been merged, consider deleting it to keep your repository clean:
+  ```bash
+  git branch -d feature-branch
+  git push origin --delete feature-branch
+  ```
+
+### 10. **Document Your Workflow**
+
+- If you're working on a team or contributing to an open-source project, document your Git workflow and practices. This helps maintain consistency and avoids confusion.
+
+By following these practices, you'll make sure your forked repository stays organized and in sync with the upstream repository, and your contributions remain easy to manage.