Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Update ReadMe

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#444 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
78/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
mysql, python
Lĩnh vực
documentation

Hướng nghiên cứu

Trước tiên, hãy đọc README.md cùng với requirements.txt, app/dbConfig.yaml, app/models/models.py, create_db.py và app.py để đối chiếu các bước thiết lập được đề xuất với dự án. Viết lại các yêu cầu trước khi cài đặt và hướng dẫn thiết lập cho macOS và Windows, bao gồm Python 3.11, MySQL, khởi tạo cơ sở dữ liệu và chạy ứng dụng. Công việc hoàn tất khi người mới đóng góp có thể làm theo README để chạy ứng dụng trên một trong hai hệ điều hành và các nội dung tham chiếu lỗi thời đã được xóa.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

The current README.md is significantly outdated and references legacy tools, EOL software versions, and deprecated cloud environments (such as Python 2.7). New contributors cannot successfully set up the project using the existing documentation.
Currently fails to run source setup.sh and create_db.py.

Proposed Action Items

  • Rewrite Prerequisites:
  • Update required Python version to Python 3.10+
  • Modernize Installation & Setup:
    • Update dependency installation steps (e.g., pip install -r requirements.txt ).
    • Clarify database initialization (create_db.py).

Additional details

The README needs to work for both macOS and Windows contributors.

What is wrong with the current README
  • Says Python 2.7 is required. The app is Python 3.
  • Tells people to clone from Bitbucket and mentions Cloud9. The repo is on GitHub.
  • Says to run source setup.sh. It also creates the venv with whatever python3 is newest on the machine.
  • Never mentions that MySQL is required. The app connects to a MySQL database (see app/dbConfig.yaml and app/models/models.py).
  • Says to use https:// to open the app. app.py does not set up SSL, so it is http://localhost:8080.
  • Refers to files and folders that no longer match the repo (for example the "File Hierarchy" section).
Known setup problems to document
  • Python version: On Python 3.14, pip install -r requirements.txt fails while building greenlet==1.1.0. The pinned packages in requirements.txt are from 2021, so the README should name a specific supported version (for example 3.11) rather than "3.10+" and warn against newer ones. Better still, update the greenlet pin in requirements.txt so the install works on newer Python.
  • MySQL setup: The app expects a database cas and a user cas_user with the password password (from app/dbConfig.yaml). The README should give the SQL to create them: 
    CREATE DATABASE IF NOT EXISTS cas;
CREATE USER IF NOT EXISTS 'cas_user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL ON cas.* TO 'cas_user'@'localhost';
What the new README should contain
  1. Prerequisites: Git, Python 3.11, MySQL (with a note on how to check the MySQL server is running on each OS).
  2. Get the code: git clone https://github.com/BCStudentSoftwareDevTeam/cas.git
  3. Create the virtual environment and install packages, with separate commands for each OS:
    • macOS: python3.11 -m venv venv then source venv/bin/activate
    • Windows (PowerShell): py -3.11 -m venv venv then venv\Scripts\Activate.ps1
  4. Create the MySQL database and user (the SQL above).
  5. Create the tables and sample data: mkdir data then python create_db.py.
  6. Run the app: python app.py, then open http://localhost:8080.
  7. Returning later: activate the venv and run python app.py.
  8. Troubleshooting, for example:
    • "Can't connect to MySQL server": the MySQL service is not running or is on a different port.
    • "Access denied for user 'cas_user'": redo the database user step.
    • pip fails building a package: check python --version is the supported version.
    • "Address already in use": another program is using port 8080.
Acceptance criteria
  • Someone with a fresh macOS or Windows machine can go from clone to a running app using only the README.
  • The README no longer mentions Python 2.7, Bitbucket or Cloud9.
  • setup.sh is either removed from the instructions or replaced by steps that work on Windows.
Ngôn ngữ chính
JavaScript
Star
0
Fork
2
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

  • Không có Dockerfile hay tệp Docker Compose
  • Không có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của BCStudentSoftwareDevTeam/cas

Tất cả issue của BCStudentSoftwareDevTeam/cas

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.