Add content on deprecating functionality
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 52/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Open Module 7 in 07_packaging.qmd and read the existing “Breaking changes” section around line 132. Add a focused section covering warning types and stacklevel, a deprecation timeline, communication practices, code and real-world examples. Done means the module explains these strategies clearly and fits the surrounding course content.
Written by the indexing model from the issue text.
Description
Problem
The course covers semantic versioning and breaking changes in Module 7, but lacks content on deprecation strategies - a critical skill for package maintainers.
Proposed Content
Add a section to Module 7 (07_packaging.qmd) covering:
1. Deprecation Warnings
- Using Python's
warningsmodule - Proper
stacklevelusage - DeprecationWarning vs FutureWarning:
DeprecationWarning: For developers (filtered by default, shown when running tests)FutureWarning: For end users (always visible, for changes affecting user code)
2. Deprecation Timeline
- Announce in version X.Y
- Remove in version (X+1).0
- Maintain for 1-2 minor releases minimum
3. Communication Strategy
- CHANGELOG updates
- Release notes
- Documentation migration guides
- Clear docstring warnings
4. Code Examples
import warnings
def old_function(x):
warnings.warn(
"old_function is deprecated and will be removed in version 2.0. "
"Use new_function instead.",
DeprecationWarning,
stacklevel=2
)
return new_function(x)
5. Real-World Examples
Reference deprecation practices from popular packages (pandas, numpy, scikit-learn).
Location
Module 7 - after the "Breaking changes" section (around line 132)
- Dominant language
- Jupyter Notebook
- Stars
- 8
- Forks
- 1
- Avg merge
- 4m
- Merged PRs (30d)
- 1
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from DHI/python-package-development
-
Difficulty 2/5 1-2 days Newbie friendliness 88/100
-
Difficulty 2/5 1-2 days Newbie friendliness 72/100
DHI/python-package-development#37 · 1 comment ·
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 3/5 1-2 days Newbie friendliness 48/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 48/100
All issues in DHI/python-package-development
Similar issues
-
user-reported
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Kong/developer.konghq.com#7316 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
HarperFast/skills#96 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
infinispan/infinispan#18150 ·
-
bug triage:deciding
Difficulty 1/5 Under an hour Newbie friendliness 88/100
open-telemetry/otel-arrow#4132 ·
-
Ecosystem: ClawMetry — the Qwen Code reader is now free and open source (follow-up to #9294 / #9338) Opencategory/integration priority/P3 scope/documentation status/ready-for-human type/feature-request
Difficulty 1/5 Under an hour Newbie friendliness 84/100