Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Update ReadMe

未关闭 适合新手
  • 哪里不对？
#444 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
78/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
mysql, python
领域
documentation

调研方向

先阅读 README.md，以及 requirements.txt、app/dbConfig.yaml、app/models/models.py、create_db.py 和 app.py，核对提议的设置步骤是否符合项目。重写 macOS 和 Windows 的前置条件与设置说明，包括 Python 3.11、MySQL、数据库初始化和运行应用。完成标准是新贡献者能够按照 README 在任一操作系统上启动应用，并且过时的引用已被移除。

由索引模型根据 Issue 内容生成。

描述

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.
主要语言
JavaScript
星标
0
派生
2
30 天内没有已合并 PR

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 没有贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

BCStudentSoftwareDevTeam/cas 的其他 Issue

查看 BCStudentSoftwareDevTeam/cas 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。