Skip to content

Commit e9b2806

Browse files
committed
Add CONTRIBUTING.md with guidelines and link it from README
Documents the file/naming conventions, how to add an alternate solution, and the common formatting mistakes seen across recent PRs (unclosed code fences, markdown inside fences, stray indentation, notebook metadata churn). Also ignores .DS_Store repo-wide. Closes #159
1 parent 0a7de33 commit e9b2806

3 files changed

Lines changed: 86 additions & 1 deletion

File tree

.gitignore

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,4 +101,6 @@ ENV/
101101
# mypy
102102
.mypy_cache/
103103

104-
clean_files.py
104+
clean_files.py
105+
# macOS
106+
.DS_Store

CONTRIBUTING.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Contributing
2+
3+
Thanks for wanting to add a solution or fix something! This repo gets a lot of
4+
first-time contributions, so here's a quick guide to keep things smooth for
5+
everyone.
6+
7+
## Finding the right file
8+
9+
Every question lives in a `Status/Day_XX.md` file (Day 1–9 are named
10+
`Day 1.md`, `Day 2.md`, ... with a space; Day 10 onward are named
11+
`Day_10.md`, `Day_11.md`, ... with an underscore — that's just a historical
12+
inconsistency, not a mistake). The [README's Practice Status
13+
table](README.md) maps question numbers to the day file that contains them.
14+
15+
Most days also have a matching notebook in `notebooks/Day_XX.ipynb` with the
16+
same content in Jupyter form. If you're adding a solution, please add it to
17+
**both** the `Status/*.md` file and the matching notebook where one exists,
18+
so they don't drift apart.
19+
20+
## Adding an alternate solution
21+
22+
Find the question's section in the day file, and add a new fenced code block
23+
right after the existing solutions for that question (before the `---`
24+
separator), following the pattern already used in the file:
25+
26+
```python
27+
'''Solution by: your-github-username
28+
'''
29+
<your code>
30+
```
31+
32+
A few things that keep solutions easy to read and merge cleanly:
33+
34+
- **Close every code fence.** An unclosed ` ```python ` block swallows
35+
everything after it in the file — including the day-navigation links at
36+
the bottom — into a code block. Before opening a PR, preview the rendered
37+
Markdown (or just double check your diff has a closing ` ``` ` for every
38+
opening one) to make sure the fence balances.
39+
- **Only put code inside the fence.** Markdown headings, `---` separators,
40+
or prose don't belong inside a ` ```python ` block — they'll render as
41+
literal text and can make the block invalid Python.
42+
- **Make sure the code actually runs as pasted.** Watch out for stray
43+
leading whitespace (accidental indentation from your editor) and remember
44+
to print/return the result — a solution that computes an answer but never
45+
prints it won't show anything when someone runs it.
46+
- **Add alongside, don't replace**, unless you're specifically fixing a bug
47+
in an existing solution. If you *are* fixing a bug, please explain what
48+
was wrong in the PR description.
49+
- **Keep notebook diffs small.** Jupyter tends to rewrite `execution_count`,
50+
cell outputs, and kernel metadata (Python version, `display_name`) on
51+
every save even when you didn't touch that cell. Where you can, avoid
52+
committing metadata/version bumps that aren't related to your change —
53+
they make diffs noisier and unrelated to review.
54+
- **One topic per PR.** A PR that touches a single question (or a single
55+
day) is much easier to review and merge than one that reshapes many days
56+
at once. If you have several unrelated additions, separate PRs are
57+
welcome.
58+
59+
## Reporting a bug in an existing solution
60+
61+
Please open an issue (or better, a PR with the fix) that includes:
62+
63+
- Which day/question is affected
64+
- What input you tested with
65+
- What output you got vs. what you expected
66+
67+
## Submitting a PR
68+
69+
1. Fork the repo and create a branch for your change.
70+
2. Make your edit(s) following the guidelines above.
71+
3. Open a PR describing what you added or fixed.
72+
73+
If you don't have push access to create a branch on your own fork for some
74+
reason, opening an issue with your solution pasted in is a fine fallback —
75+
a maintainer can fold it in.
76+
77+
## Code style
78+
79+
This is a beginner-friendly exercise repo, not a production codebase — clear
80+
and correct beats clever. There's no enforced linter; just try to match the
81+
style of the surrounding solutions in the file you're editing.

README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515

1616
***In this repository, I will be gradually updating the codebase of the given problems with my own solutions. Also, I may try to explain the code and tell my opinion about the problem if needed. Main Authors solutions are in python 2 & my solutions will be in python 3. Every problem is divided into a template format which is discussed below. There is a [discussion](https://github.com/darkprinx/100-plus-Python-programming-exercises-extended/issues/3) section so don't forget to share your opinion, ideas and feel free to discuss anything wrong or mistake***
1717

18+
***Want to add your own solution or fix something? See [CONTRIBUTING.md](CONTRIBUTING.md) for a quick guide.***
19+
1820
***A Big Thanks to [apurvmishra99](https://github.com/apurvmishra99) for contributing the repository by cleaning up the formatting of all Days_.md files. fixing some random errors, fixing some variable naming with PEP8 conventions, and adding a whole new folder of [jupyter](https://github.com/darkprinx/100-plus-Python-programming-exercises-extended/tree/master/notebooks) notebook of all 24 days.***
1921

2022
----------------

0 commit comments

Comments
 (0)