The repository is the permanent technical record of the project and part of the deliverable. It should let anyone understand, inspect, reproduce, review, and continue the work.
A good repository lets another student, researcher, instructor, or developer:
A repository is not just storage; it is evaluated for clarity, completeness, organization, and reproducibility.
Fifteen parts, from naming and structure through reproducibility and the final checklist.
Give the repository a meaningful name that reflects the project.
Add a short description covering the problem, the main approach, and the main output.
project-name/
|
|-- README.md
|-- requirements.txt
|-- environment.yml
|-- LICENSE
|
|-- slides/
| |-- proposal.pptx / proposal.pdf
| |-- midterm.pptx / midterm.pdf
| |-- final.pptx / final.pdf
|
|-- src/
| |-- data/ models/ training/ evaluation/ utils/
|
|-- notebooks/
| |-- 01_data_exploration.ipynb
| |-- 02_baseline.ipynb
| |-- 03_experiments.ipynb
|
|-- data/
| |-- raw/ processed/ samples/
|
|-- configs/
|-- results/
| |-- metrics/ predictions/ experiment_logs/
|
|-- visuals/
| |-- visual_abstract.png pipeline.png result_figures/
|
|-- tests/The exact structure may differ, but it must be logical and easy to navigate.
Explain the real-world problem, why it matters, who benefits, and why existing solutions fall short. Keep it concise but specific.
Define the input, the output, the technical task, the target use case, and the important constraints. Add representative input and output examples.
Add one clear figure that summarizes the project: input, major processing stages, the model or system, the output, and the practical use. It should be understandable without reading the full repository.
For every dataset, document:
For generated or labeled data, also describe the generation or collection process, the labeling instructions, the quality checks, and the validation procedure.
Do not commit sensitive, restricted, or copyrighted data without permission. When the full dataset cannot be included, provide sample files, download instructions, preparation scripts, and the expected folder structure.
Describe the complete flow: the models used, the role of each, preprocessing, training, inference, and post-processing. Include a pipeline diagram, and for each major model explain why it was chosen and how it was configured.
Document:
Store the important prompts, configurations, and generation scripts in the repository.
Document:
Provide exact commands, for example:
python -m src.training.train \
--config configs/baseline.yamlExplain the test-set construction, the evaluation metrics, the baseline methods, the comparison models, the evaluation scripts, the qualitative evaluation procedure, and human evaluation when used.
Provide exact commands, for example:
python -m src.evaluation.evaluate \
--config configs/final_model.yamlPresent the main results in readable tables.
| Model | Accuracy | Macro-F1 | Latency |
|---|---|---|---|
| Baseline | 0.78 | 0.65 | 20 ms |
| Model A | 0.84 | 0.76 | 35 ms |
| Final model | 0.88 | 0.81 | 42 ms |
Link to detailed CSV or JSON results, prediction files, experiment logs, and figures. The numbers in the README, the slides, and the result files must match.
The repository must let another person run the project. Include:
Use relative paths and configuration files; do not depend on undocumented local folders.
Never commit:
Use environment variables and provide a .env.example file.
Code should be organized into meaningful modules, readable, documented where needed, free of unused files and hard-coded local paths, consistent in naming, and runnable from a clean environment.
Notebooks should run top to bottom, have clear headings, separate exploration from final experiments, avoid excessive output, and explain important decisions.
List every team member and their responsibilities, with concrete contributions such as dataset collection, labeling, model implementation, experimentation, evaluation, interface development, and documentation.
Every member is expected to understand the whole project, not only their own files.
A strong submission shows both the quality of the project and the professionalism of the team.
Show, don't just tell. A few well-labeled figures make the input, the processing, and the results legible at a glance. Aim for at least these four, each with a caption, in the README and the visuals/ folder.
Put concrete examples in the README, and link them from the slides: sample data (images or text), how the data is generated, the model steps, real model inputs and outputs, and several clear error cases.
This is a quick final check, not a replacement for the full guide. Read the complete requirements above first, then use these ten items to confirm the major pieces are in place before you submit.