docs: update CONTRIBUTING.md guide
#81
Conversation
WalkthroughThe changes in this pull request involve significant enhancements to the Changes
Possibly related PRs
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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 (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (7)
CONTRIBUTING.md (7)
14-15: Add a comma for better readabilityConsider adding a comma before 'so' to improve the sentence structure.
-A gradle wrapper is included so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given +A gradle wrapper is included, so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...# Building A gradle wrapper is included so these tasks can run without any prior i...(COMMA_COMPOUND_SENTENCE_2)
29-31: Consider documenting available modulesThe build command specifically targets the 'chat-android' module. Consider listing all available modules and their purposes for better clarity.
41-47: Enhance Detekt documentationConsider adding:
- Information about interpreting Detekt reports
- Common issues and how to fix them
- Location of Detekt configuration file
49-58: Expand test documentationConsider enhancing this section with:
- Test organization/structure
- Different types of tests available
- Location and interpretation of test reports
- Instructions for writing new tests
61-62: Simplify the introductionConsider rephrasing for clarity and conciseness.
-If you wish to make changes to the source code and test them immediately in another project, follow these steps: +To test local changes in another project, follow these steps:🧰 Tools
🪛 LanguageTool
[style] ~61-~61: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...(MAKE_CHANGES)
67-69: Use placeholder version numberConsider using a more generic placeholder to prevent confusion.
-VERSION_NAME=0.1.0-local.1 +VERSION_NAME=X.Y.Z-local.1 # Replace X.Y.Z with the current version
133-135: Use placeholder version in exampleConsider using placeholders in the example command to prevent it from becoming outdated.
-github_changelog_generator -u ably -p ably-chat-kotlin --since-tag v1.2.3 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS +github_changelog_generator -u ably -p ably-chat-kotlin --since-tag vX.Y.Z --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS # Replace X.Y.Z with the previous version
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
CONTRIBUTING.md(3 hunks)build.gradle.kts(0 hunks)
💤 Files with no reviewable changes (1)
- build.gradle.kts
🧰 Additional context used
🪛 LanguageTool
CONTRIBUTING.md
[uncategorized] ~14-~14: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...# Building A gradle wrapper is included so these tasks can run without any prior i...
(COMMA_COMPOUND_SENTENCE_2)
[style] ~61-~61: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...
(MAKE_CHANGES)
Code Coverage
|
Added section about: - building - testing - code style - using local build as a dependency
ttypic
force-pushed
the
update-contributing-guide
branch
from
46f4d18 to
0323879
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (7)
CONTRIBUTING.md (7)
14-15: Minor grammatical improvement neededConsider adding a comma for better readability:
-A gradle wrapper is included so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given +A gradle wrapper is included, so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...# Building A gradle wrapper is included so these tasks can run without any prior i...(COMMA_COMPOUND_SENTENCE_2)
27-31: Add output location informationConsider adding information about where the built AAR package will be located after the build command.
To build the library's AAR package, execute: ```bash ./gradlew chat-android:assemble+The built AAR package will be available in the
chat-android/build/outputs/aar/directory.--- `41-47`: **Enhance Detekt documentation** Consider adding information about: 1. How to interpret and handle Detekt findings 2. Whether Detekt checks are enforced in CI/CD ```diff #### Running Detekt Locally You can run Detekt locally to verify your code against the configured rules. Use the following command: ```bash ./gradlew detekt
+The command will generate a report highlighting any issues found. The report can be found at
build/reports/detekt/.
+
+> [!NOTE]
+> Detekt checks are also run automatically in our CI/CD pipeline for all pull requests.--- `54-62`: **Expand test documentation** Consider adding more detailed information about: 1. Different types of tests (unit, integration, etc.) 2. Test report locations 3. How to debug test failures ```diff ### Running Tests Our tests are written using JUnit and can be executed with the following command: ```bash ./gradlew testThis will run all unit tests in the project. Ensure all tests pass before submitting a pull request.
+
+#### Test Reports
+Test reports can be found in thebuild/reports/tests/directory after running the tests.
+
+#### Debugging Test Failures
+For detailed test output, you can run:
+bash +./gradlew test --info +--- `66-67`: **Consider rephrasing for conciseness** The current wording could be more direct: ```diff -If you wish to make changes to the source code and test them immediately in another project, follow these steps: +To test local changes in another project, follow these steps:🧰 Tools
🪛 LanguageTool
[style] ~66-~66: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...(MAKE_CHANGES)
101-104: Add cleanup instructionsConsider adding instructions for cleaning up local development setup:
> [!NOTE] > - Ensure the version number (`0.1.0-local.1`) matches the one you set in gradle.properties. > - The `mavenLocal()` repository should typically be used only during development to avoid conflicts with published versions in remote repositories. +> - After testing, remember to remove the mavenLocal() repository and revert to the published version to avoid unintended usage of local builds.
138-145: Fix indentation in changelog sectionThe indentation of the list items could be improved for better readability:
- - The command you will need to run will look something like this: - `github_changelog_generator -u ably -p ably-chat-kotlin --since-tag v1.2.3 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`. - Generate token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token). - - Using the command above, `--output delta.md` writes changes made after `--since-tag` to a new file. - - The contents of that new file (`delta.md`) then need to be manually inserted at the top of the `CHANGELOG.md`, changing the " - Unreleased" - heading and linking with the current version numbers. - - Also ensure that the "Full Changelog" link points to the new version tag instead of the `HEAD`. +- The command you will need to run will look something like this: + `github_changelog_generator -u ably -p ably-chat-kotlin --since-tag v1.2.3 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`. + Generate token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token). +- Using the command above, `--output delta.md` writes changes made after `--since-tag` to a new file. +- The contents of that new file (`delta.md`) then need to be manually inserted at the top of the `CHANGELOG.md`, changing the "Unreleased" + heading and linking with the current version numbers. +- Also ensure that the "Full Changelog" link points to the new version tag instead of the `HEAD`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
CONTRIBUTING.md(3 hunks)build.gradle.kts(0 hunks)
💤 Files with no reviewable changes (1)
- build.gradle.kts
🧰 Additional context used
🪛 LanguageTool
CONTRIBUTING.md
[uncategorized] ~14-~14: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...# Building A gradle wrapper is included so these tasks can run without any prior i...
(COMMA_COMPOUND_SENTENCE_2)
[style] ~66-~66: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...
(MAKE_CHANGES)
Co-authored-by: sachin shinde <sachinshinde7676@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (7)
CONTRIBUTING.md (7)
27-31: Add information about the output locationThe command explanation should include where to find the built artifact.
Add the output location information:
```bash ./gradlew chat-android:assemble
+The built AAR package will be available in the
chat-android/build/outputs/aar/directory.--- `51-52`: **Use relative link for configuration file** Using an absolute GitHub URL can break when the repository is forked. ```diff -Detekt's rules can be updated by modifying the [detekt.yml](https://github.com/ably/ably-chat-kotlin/blob/main/detekt.yml) configuration +Detekt's rules can be updated by modifying the [detekt.yml](./detekt.yml) configuration
43-47: Add information about viewing Detekt reportsThe section should include where to find the Detekt reports after running the check.
You can run Detekt locally to verify your code against the configured rules. Use the following command: ```bash ./gradlew detekt
+After running Detekt, you can find the HTML report at
build/reports/detekt/detekt.html.--- `58-62`: **Add information about test reports location** Include where developers can find the test reports for debugging failures. ```diff ```bash ./gradlew test
+Test reports can be found in the
build/reports/tests/test/index.htmlfile.--- `66-67`: **Improve clarity of the introduction** The current wording could be more concise. ```diff -If you wish to make changes to the source code and test them immediately in another project, follow these steps: +To test source code changes immediately in another project, follow these steps:🧰 Tools
🪛 LanguageTool
[style] ~66-~66: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...(MAKE_CHANGES)
73-74: Use placeholder version numbersUsing specific version numbers in examples can become outdated. Consider using placeholder versions.
-VERSION_NAME=0.1.0-local.1 +VERSION_NAME=X.Y.Z-local.1- implementation("com.ably.chat:chat-android:0.1.0-local.1") + implementation("com.ably.chat:chat-android:X.Y.Z-local.1")Also applies to: 98-99
142-144: Fix line wrapping in changelog instructionsThe word "Unreleased" is split across lines, which affects readability.
- heading and linking with the current version numbers. - - Also ensure that the "Full Changelog" link points to the new version tag instead of the `HEAD`. + heading and linking with the current version numbers. + - Also ensure that the "Full Changelog" link points to the new version tag instead of the `HEAD`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
CONTRIBUTING.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
CONTRIBUTING.md
[style] ~66-~66: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...
(MAKE_CHANGES)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (5)
CONTRIBUTING.md (5)
14-14: Fix grammatical issue in the sentenceThe sentence ends awkwardly with "given". Consider rewording for better clarity.
-A gradle wrapper is included, so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given +A gradle wrapper is included, so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands is:
41-41: Add information about handling Detekt findingsConsider adding guidance on how to interpret and address Detekt findings, including:
- Where to find the Detekt report
- How to handle false positives
- Common issues and their solutions
64-64: Enhance test documentation with additional detailsConsider adding information about:
- Different types of tests available (unit, integration, etc.)
- Location of test reports
- How to debug failed tests
- Test coverage requirements
68-68: Improve sentence structure for clarityThe current wording is a bit verbose. Consider a more direct approach.
-If you wish to make changes to the source code and test them immediately in other projects, follow these steps: +To test source code changes immediately in other projects, follow these steps:🧰 Tools
🪛 LanguageTool
[style] ~68-~68: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...(MAKE_CHANGES)
140-147: Enhance changelog generation documentationConsider adding:
- Example of the expected changelog format
- Security note about handling the GitHub token
- Explanation of when to use different changelog generator options
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
CONTRIBUTING.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
CONTRIBUTING.md
[style] ~68-~68: Consider shortening or rephrasing this to strengthen your wording.
Context: ...cally in other projects If you wish to make changes to the source code and test them immediate...
(MAKE_CHANGES)
Added section about:
Summary by CodeRabbit
Documentation
CONTRIBUTING.mdfile with new sections on building the project, code standards, and running tests.chat-androidlocally and updated the "Release Process" section for better understanding.Chores
mavenLocal()from thebuild.gradle.ktsfile.checktask runs thedetekttask during checks.