docs: add CONTRIBUTING.md #275
Conversation
WalkthroughA new CONTRIBUTING.md file was added to provide contributor guidelines, including development setup and workflow instructions. Simultaneously, the "Contributing" section was removed from the README.md file, relocating all development and contribution guidance to the new dedicated documentation file. Changes
Suggested labels
Tip ⚡️ Faster reviews with caching
Enjoy the performance boost—your workflow just got faster. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
CONTRIBUTING.md (4)
1-4: Clarify project context in document title
Consider specifying the project name in the main heading for clarity (especially if this file is viewed outside the repo). For example:- # Contributing + # Contributing to the MCP Go SDK
8-14: Refine prerequisite instruction for clarity
The phrasing “Make sure you have Go 1.23 or later installed on your machine” can be more direct. For example:- Make sure you have Go 1.23 or later installed on your machine. You can check your Go version by running: + Ensure Go 1.23 or later is installed on your machine by running:🧰 Tools
🪛 LanguageTool
[grammar] ~9-~9: It appears that the past participle should be used here.
Context: ... ### Prerequisites Make sure you have Go 1.23 or later installed on your machine...(HAVE_PART_AGREEMENT)
30-39: Encourage descriptive commits and formatting
Consider adding a guideline around commit messages and code style. For example, after “Make your changes.”:- 2. Make your changes. + 2. Make your changes. + - Write clear, descriptive commit messages. + - Run `go fmt ./...` and any project-specific linters before committing.
42-42: Fix missing comma in closing sentence
Insert a comma before “either” for proper punctuation:- Feel free to reach out if you have any questions or need help either by [opening an issue](https://github.com/mark3labs/mcp-go/issues) or by reaching out in the [Discord channel](https://discord.gg/RqSS2NQVsY). + Feel free to reach out if you have any questions or need help, either by [opening an issue](https://github.com/mark3labs/mcp-go/issues) or by reaching out in the [Discord channel](https://discord.gg/RqSS2NQVsY).🧰 Tools
🪛 LanguageTool
[uncategorized] ~42-~42: Possible missing comma found.
Context: ...h out if you have any questions or need help either by [opening an issue](https://gi...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
CONTRIBUTING.md(1 hunks)README.md(0 hunks)
💤 Files with no reviewable changes (1)
- README.md
🧰 Additional context used
🪛 LanguageTool
CONTRIBUTING.md
[grammar] ~9-~9: It appears that the past participle should be used here.
Context: ... ### Prerequisites Make sure you have Go 1.23 or later installed on your machine...
(HAVE_PART_AGREEMENT)
[style] ~41-~41: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...mit a pull request to the main branch. Feel free to reach out if you have any questions or ...
(FEEL_FREE_TO_STYLE_ME)
[uncategorized] ~42-~42: Possible missing comma found.
Context: ...h out if you have any questions or need help either by [opening an issue](https://gi...
(AI_HYDRA_LEO_MISSING_COMMA)
| 1. Fork the repository | ||
| 2. Clone your fork: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/YOUR_USERNAME/mcp-go.git | ||
| cd mcp-go | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add a step to configure the upstream remote
We should guide contributors to keep their fork in sync with the main repo. Suggest inserting after cloning:
3. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/mcp-go.git
cd mcp-go-
- Add the upstream remote:
-
- git remote add upstream https://github.com/mark3labs/mcp-go.git
-
-
- Install the required packages:
go mod tidy
<!-- This is an auto-generated reply by CodeRabbit -->
There was a problem hiding this comment.
Ya, good idea (though I personally prefer using gh CLI for this)
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What are the GitHub CLI (gh) commands for adding upstream remote and keeping a fork in sync?
💡 Result:
Adding an Upstream Remote to a Fork
To keep your fork in sync with the original repository ("upstream"), you first need to set up a remote pointing to the upstream repository. You can do this via git or the GitHub CLI.
Using Git:
git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.gitVerify setup:
git remote -vYou should see both origin (your fork) and upstream (original repo) listed[1][7][9].
Using GitHub CLI (gh):
When you fork a repository using gh, you can also automatically set up the upstream remote:
gh repo fork REPOSITORY --remote=trueThis will add the upstream remote in one step[9][3].
Keeping a Fork in Sync
There are two main ways to sync your fork with the upstream repository using GitHub CLI.
1. Using gh repo sync (GitHub CLI Recommended)
To update your fork’s branch (e.g., main) with the upstream’s changes:
gh repo sync owner/cli-fork -b main- Replace
owner/cli-forkwith your fork’s identifier. - Replace
mainwith your default or target branch. - Use the
--forceflag if there are conflicts and you want to overwrite your branch[10].
2. Using Raw Git Commands
This is a manual alternative, useful if you want more granular control:
- Fetch the upstream changes:
git fetch upstream
- Check out your local main branch:
git checkout main
- Merge upstream changes:
git merge upstream/main
- Push the update to your fork:
git push origin main
This keeps your fork's main branch up-to-date with the original repository[7][6][10].
Summary Table
| Task | GitHub CLI (gh) Command |
Git Command |
|---|---|---|
| Fork and add upstream remote | gh repo fork REPOSITORY --remote=true |
git remote add upstream <upstream-url> |
| Sync fork branch with upstream (CLI) | gh repo sync owner/fork-repo -b main |
N/A |
| Fetch and merge upstream into local | N/A | git fetch upstreamgit merge upstream/main |
| Push changes to your fork | N/A | git push origin main |
Best Practices
- After syncing, push your updated branch to your fork’s origin to keep GitHub in sync[7][6].
- Always resolve any merge conflicts that arise before pushing.
These commands allow you to efficiently add an upstream remote and keep your fork synchronized with the original repository using both GitHub CLI and traditional git methods[1][3][10].
Citations:
- 1: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork
- 2: https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories
- 3: https://cli.github.com/manual/gh_repo_fork
- 4: How to correctly checkout a remote upstream branch? cli/cli#3847
- 5: https://www.atlassian.com/git/tutorials/git-forks-and-upstreams
- 6: https://www.sitepoint.com/quick-tip-synch-a-github-fork-via-the-command-line/
- 7: https://graphite.dev/guides/upstream-remote
- 8: https://github.blog/open-source/git/how-the-github-cli-can-now-enable-triangular-workflows/
- 9: https://docs.github.com/articles/fork-a-repo
- 10: https://docs.github.com/articles/syncing-a-fork
@robert-jackson-glean Thanks for the feedback! You're right - GitHub CLI is a great alternative. Let's include both options to accommodate different preferences:
3. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/mcp-go.git
cd mcp-go-
- Add the upstream remote (choose one method):
- Using standard git:
-
- git remote add upstream https://github.com/mark3labs/mcp-go.git
-
- OR using GitHub CLI:
-
- gh repo set-default mark3labs/mcp-go
-
-
- Install the required packages:
go mod tidy
This way, contributors can use whichever method they're most comfortable with.
---
<details>
<summary>✏️ Learnings added</summary>
Learnt from: robert-jackson-glean
PR: #275
File: CONTRIBUTING.md:17-23
Timestamp: 2025-05-12T15:59:13.092Z
Learning: For CONTRIBUTING.md documentation, include both standard git commands and GitHub CLI (gh) alternatives when describing repository setup steps to accommodate different user preferences.
> Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
</details>
<!-- <agentComponentType>chat-answer</agentComponentType> -->
<!-- <rawResChunk><answer><details>
<summary>🧩 Analysis chain</summary>
🌐 Web query:
```web
What are the GitHub CLI (gh) commands for adding upstream remote and keeping a fork in sync?
💡 Result:
Adding an Upstream Remote to a Fork
To keep your fork in sync with the original repository ("upstream"), you first need to set up a remote pointing to the upstream repository. You can do this via git or the GitHub CLI.
Using Git:
git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.gitVerify setup:
git remote -vYou should see both origin (your fork) and upstream (original repo) listed[1][7][9].
Using GitHub CLI (gh):
When you fork a repository using gh, you can also automatically set up the upstream remote:
gh repo fork REPOSITORY --remote=trueThis will add the upstream remote in one step[9][3].
Keeping a Fork in Sync
There are two main ways to sync your fork with the upstream repository using GitHub CLI.
1. Using gh repo sync (GitHub CLI Recommended)
To update your fork’s branch (e.g., main) with the upstream’s changes:
gh repo sync owner/cli-fork -b main- Replace
owner/cli-forkwith your fork’s identifier. - Replace
mainwith your default or target branch. - Use the
--forceflag if there are conflicts and you want to overwrite your branch[10].
2. Using Raw Git Commands
This is a manual alternative, useful if you want more granular control:
- Fetch the upstream changes:
git fetch upstream
- Check out your local main branch:
git checkout main
- Merge upstream changes:
git merge upstream/main
- Push the update to your fork:
git push origin main
This keeps your fork's main branch up-to-date with the original repository[7][6][10].
Summary Table
| Task | GitHub CLI (gh) Command |
Git Command |
|---|---|---|
| Fork and add upstream remote | gh repo fork REPOSITORY --remote=true |
git remote add upstream <upstream-url> |
| Sync fork branch with upstream (CLI) | gh repo sync owner/fork-repo -b main |
N/A |
| Fetch and merge upstream into local | N/A | git fetch upstreamgit merge upstream/main |
| Push changes to your fork | N/A | git push origin main |
Best Practices
- After syncing, push your updated branch to your fork’s origin to keep GitHub in sync[7][6].
- Always resolve any merge conflicts that arise before pushing.
These commands allow you to efficiently add an upstream remote and keep your fork synchronized with the original repository using both GitHub CLI and traditional git methods[1][3][10].
Citations:
- 1: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork
- 2: https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories
- 3: https://cli.github.com/manual/gh_repo_fork
- 4: How to correctly checkout a remote upstream branch? cli/cli#3847
- 5: https://www.atlassian.com/git/tutorials/git-forks-and-upstreams
- 6: https://www.sitepoint.com/quick-tip-synch-a-github-fork-via-the-command-line/
- 7: https://graphite.dev/guides/upstream-remote
- 8: https://github.blog/open-source/git/how-the-github-cli-can-now-enable-triangular-workflows/
- 9: https://docs.github.com/articles/fork-a-repo
- 10: https://docs.github.com/articles/syncing-a-fork
@robert-jackson-glean Thanks for the feedback! You're right - GitHub CLI is a great alternative. Let's include both options to accommodate different preferences:
3. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/mcp-go.git
cd mcp-go-
- Add the upstream remote (choose one method):
- Using standard git:
-
- git remote add upstream https://github.com/mark3labs/mcp-go.git
-
- OR using GitHub CLI:
-
- gh repo set-default mark3labs/mcp-go
-
-
- Install the required packages:
go mod tidy
This way, contributors can use whichever method they're most comfortable with.
---
<details>
<summary>✏️ Learnings added</summary>
Learnt from: robert-jackson-glean
PR: #275
File: CONTRIBUTING.md:17-23
Timestamp: 2025-05-12T15:59:13.092Z
Learning: For CONTRIBUTING.md documentation, include both standard git commands and GitHub CLI (gh) alternatives when describing repository setup steps to accommodate different user preferences.
> Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure [review instructions](https://docs.coderabbit.ai/guides/review-instructions). You can manage existing learnings in the [app](https://app.coderabbit.ai/learnings).
</details>
</answer></rawResChunk> -->
<!-- This is an auto-generated reply by CodeRabbit -->
| 1. Fork the repository | ||
| 2. Clone your fork: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/YOUR_USERNAME/mcp-go.git | ||
| cd mcp-go | ||
| ``` |
There was a problem hiding this comment.
Ya, good idea (though I personally prefer using gh CLI for this)
Moves the contributing guide in the readme to a new CONTRIBUTING.md file and reorganize it a bit.
This is an initial version and soon we need to also add about testing with your own fork on an external project (using
replace) and about the examples etc. It needs some changes around the examples as well so it can be updated later. Now, let's just move it to a separate file and have a practical structure for it so that others can also add to it.Summary by CodeRabbit