Install the environment
Make sure to
update your local pandas
with the latest upstream changes
Your local organizers will assign you a documentation page
what the functionality you're documenting does
Check the current
Use a jupyter notebook to experiment
Find where the docstring is in the source code
Check if the docstring is reused by other functions/methods
You have a
guide about sharing docstrings
If it is,
who is working in the other functions
Contact them to make sure you don't have code conflicts, or you do repeated work
instructions on how to write a good docstring
Every detail is important
Doing it fast will make the process slower, and you will waste reviewers time
The changes will only get approved when they are
, and make sure you don't have errors
Build the html version
of the documentation
Show the html version to someone in your sprint who has not work on it
Does this person understand what the function does, and is able to use it in a toy example?
Is everything explained in a clear way? Is there any part that is not well understood?
Is the language correct? Are there grammar mistakes or typos?
Can the page be simplified? Is there anything that doesn't add value?
Checking the text version of the docstring, does it follow all the standards from the documentation?
Validate that there are no PEP-8 issues
git diff upstream/master -u -- "*.py" | flake8 --diff
Commit and push
Open the pull request
Make sure the description is
DOC: update the <your-function> docstring
Review if you did all the validations enumerated in the description
Mark them with
if you did, do the validation
sending the PR if you didn't
If you completed EVERY step in this list, you can finally open the PR
Now you can take a rest, help other people, make new friends... :)
Your PR will be reviewed by other people, who will help make it even better
Make the changes and discuss the PR until it's approved
You should also review
other people PRs
Be nice, concise and clear
In general it's better of avoid comments in a PR with only "Thank you", "Understood", "I'll do it"...