docs: add CONTRIBUTING.md and improve README with quick start#30
Open
dashitongzhi wants to merge 1 commit into
Open
docs: add CONTRIBUTING.md and improve README with quick start#30dashitongzhi wants to merge 1 commit into
dashitongzhi wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds contributor onboarding documentation and extends the README with a Quick Start and an architecture overview to lower the barrier to entry for new contributors.
Changes:
- Added a new
CONTRIBUTING.mdwith setup, guidelines, and PR/issue processes. - Appended a Quick Start section to
README.md. - Added a brief “Architecture” module overview to
README.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| README.md | Adds Quick Start + Architecture sections (but currently introduces internal inconsistencies/duplication with existing README content). |
| CONTRIBUTING.md | Introduces contributor setup/process guide (but DB credential guidance currently conflicts with repo defaults). |
Comments suppressed due to low confidence (2)
README.md:386
- README now contains two separate License sections (existing "## 📄 License" earlier and a new "## License" here). This duplication can confuse readers and creates conflicting structure—please remove the second License section or consolidate the text into the existing one.
## License
MIT License - see LICENSE file for details.
README.md:371
- The Quick Start instructions for Ollama don't match the rest of the README: earlier sections require creating/loading the
metatron-qwenmodel (and even describe running it in a separate terminal), but Quick Start only runsollama serve &. As written, users can follow Quick Start and still fail due to missing model setup—please align Quick Start with the documented model workflow (create/pull/run) or explicitly reference those steps.
# Start Ollama (required for AI features)
ollama serve &
# Run METATRON
python metatron.py
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+359
to
+366
| ```bash | ||
| # Clone and setup | ||
| git clone https://github.com/sooryathejas/METATRON.git | ||
| cd METATRON | ||
|
|
||
| # Install dependencies | ||
| pip install -r requirements.txt | ||
|
|
Comment on lines
+14
to
+35
| ```sql | ||
| CREATE DATABASE metatron; | ||
| CREATE USER 'metatron'@'localhost' IDENTIFIED BY 'your_password'; | ||
| GRANT ALL ON metatron.* TO 'metatron'@'localhost'; | ||
| ``` | ||
|
|
||
| 3. **Python Dependencies** | ||
| ```bash | ||
| pip install -r requirements.txt | ||
| ``` | ||
|
|
||
| 4. **Configuration** | ||
| Edit `db.py` to match your database credentials: | ||
| ```python | ||
| def get_connection(): | ||
| return mysql.connector.connect( | ||
| host="localhost", | ||
| user="metatron", | ||
| password="your_password", # Update this | ||
| database="metatron" | ||
| ) | ||
| ``` |
|
Thank you for your effort in improving the project's documentation. While
the addition of a contribution guide and quick-start instructions is a
great initiative, a detailed review of the proposed changes has revealed
several critical inconsistencies and bad practices that prevent this PR
from being merged in its current state.
Please address the following issues and implement the recommendations below:
1. Architectural Inconsistencies & Redundancies
-
*Duplicate Sections:* The PR introduces duplicated ## License and ##
Quick Start sections within README.md. This breaks the file structure
and confuses new users.
-
*Incomplete Setup Instructions:* The new Quick Start guide completely
omits necessary prerequisites previously documented, such as creating and
activating the virtual environment, which will lead to setup failures for
new contributors.
2. Security and Database Configuration Concerns
-
*Hardcoded Credentials:* Instructing contributors to directly modify
db.py with their database passwords is a major anti-pattern. Hardcoding
credentials risks accidental commits of sensitive data to the repository
history.
-
*Mismatch with Defaults:* The credentials provided in the new guide
conflict with the repository's default configuration (username: metatron,
password: 123).
3. Missing Ollama Dependencies
-
The quick-start block only calls ollama serve & but fails to mention
pulling or creating the specific model (metatron-qwen) required by the
system, leading to immediate runtime errors.
…------------------------------
Recommendations for Improvement
To get this PR approved, please refactor the changes according to these
standards:
-
*Implement Environment Variables (.env):* Remove any instructions
requiring direct code modification for configuration. Instead, utilize a
.env file approach. Provide a .env.example template and update db.py to
fetch credentials securely using os.getenv().
-
*Consolidate and Streamline:* Merge the duplicate sections in README.md.
Link the Quick Start section directly to the pre-existing, verified
installation steps instead of rewriting them inaccurately.
-
*Align Ollama Workflow:* Ensure the Ollama setup instructions explicitly
include the required model creation steps (pull/create) to ensure a
working end-to-end environment.
-
*Enforce Python Versioning:* Explicitly define the recommended Python
environment version (e.g., Python 3.10+) in CONTRIBUTING.md to avoid
dependency conflicts among contributors.
Please update your branch with these fixes so we can proceed with the
review.
Message ID: ***@***.***>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary\n\nThis PR adds:\n\n1. CONTRIBUTING.md - Comprehensive guide for new contributors\n - Setup instructions for Python 3.8+, MariaDB, and Ollama\n - Database configuration guide\n - Code guidelines and best practices\n - PR and issue reporting process\n\n2. README.md improvements - Added Quick Start section and architecture overview\n\nThese changes lower the barrier to entry for new contributors and improve documentation quality.