Wrote these public notes as I went through the first contribution instructions to submit a PR for #37093.
Each horizontal line indicates a separate stumbling point or thought while I went through it.
I could see going through these notes and creating related tickets to help the instructions and therefore experience/flow for first-time contributors.
I can do that when I have some time in the future, but if anyone has time before I do to make tickets / address them with PRs if the tickets are accepted, you’re more than welcome to take any ideas from my notes below. Especially could be useful if you’re a brand new contributor who hasn’t submitted a ticket or PR yet but wants kind of an easier one to get a feel for the process since these would be pretty much all small documentation edits and ones that are specifically about the first-time contribution experience.
The notes are messy and not fully cleaned up yet – I thought it more important to just get it out with the time I had than clean it up further. But, yeah sorry it’s not so cute 
I’m happy to clarify if anything is unclear and definitely would clean up if putting any of this into Trac. Also I didn’t fully evaluate if everything here should be put in Trac - they’re just some messy notes on the experience for now
—————————————————————————————————
1
write first contribution instructions
Some code blocks are missing the copy capability - Missing it are:
**$** source \~/.virtualenvs/djangodev/bin/activate
**$** . \~/.virtualenvs/djangodev/bin/activate
There are other code blocks that don’t have it but they are more like example code or example terminal messages and less like commands someone is likely to actually copy (idk if those are supposed to be always anyway)
—————————————————————————————————
2
How to find the path to do the
**$** python -m pip install -e /path/to/your/local/clone/django/
Part of write first contribution instructions
Feel kind of silly about flagging this but it did make me have to go look it up and pulled me away from what I was doing and since the instructions are putting in stuff like git, maybe something about this should be in there too
Specifically, I ultimately did: `pip install -e ~/Desktop/code/django` and the info I found that actually helped me was knowing that
• ~ is a shortcut for home directory
- On macOS, home directory is:
/Users/yourusername/
If you see a path like \~/Desktop/myfile.txt it actually means /Users/yourusername/Desktop/myfile.txt
echo $USER\ in terminal will will print your username.
And if it shows (djangodev) username@MacBook-Pro
"MacBook-Pro = hostname of your Mac. It’s the name you gave your computer when you set it up.
—————————————————————————————————
3
I don’t understand this: “The installed version of Django is now pointing at your local copy by installing in editable mode. You will immediately see any changes you make to it, which is of great help when testing your first contribution.”
Specifically “…installing in editable mode. You will immediately see any changes you make to it…”
didn’t seem to affect what I was doing much so fine to ignore for now I guess
—————————————————————————————————
4
After running tests, I’m still in the “tests” directory instead of the general one (because I moved to tests to run the command as instructed (“Before running the test suite, enter the Django tests/ directory using the cd tests command, and install test dependencies by running:”)
Am I supposed to move back to the directory or does it not matter if I stay in the tests directory?
I feel like I’m supposed to move back, right?
Maybe recommend adding something like:
Run command `cd ..` to go back to the django directory instead of the django/tests (where you were before running the tests)
This is confirmed when it later has “cd to the Django tests/ directory and run:” again (or if not needed to make the branch, this line can be removed or edited to “you should still be in the tests/ directory”)…it actually says to change back to the tests directory several times without ever saying to leave it with a cd so idk but I guess I did get through it fine ultimately
write first contribution instructions
—————————————————————————————————
5
Might be good to include a sentence of what the documentation syntax/language is…e.g. it’s not markdown…what is this strangeness
—————————————————————————————————
6
How can I credit the reviewer in a commit message for a commit that hasn’t been reviewed yet since it’s not yet committed….I don’t get that? Seems like paradox. How could anyone? prob relates to some specific situations I just don’t know about yet
committing code django docs
—————————————————————————————————
7
That i / esc / :wq editor mode thing is not familiar pretty weird/intimidating looking if not encountered before. Should include info about that coming up when you do `git commit`? and whatever mode that’s called (I think I’ve read its name before - look up)
write first contribution instructions - test section
Should include there and/or also in the commit message guidelines linked from above link in that section
—————————————————————————————————
8
It’s not clear to me if there’s an easier way people do the 72 character limit for lines in commit messages….I opened a word counter and copy and pasted and went back and forth while editing and I’m pretty positive that was not the easiest way to do that….
—————————————————————————————————
9
It’s pretty unclear/confusing on whether I should be writing on forum, in the ticket thread, or in the GitHub PR for any given question. Some things more obvious than others, but ultimately it feels odd to have the same conversation spread across three things. What’s the source of truth? Trac I think? But to feel well-organized you’d still have to reference each thing in each place
—————————————————————————————————
10
“You can create a pull request by visiting the Django GitHub page. You’ll see your branch under “Your recently pushed branches”. Click “Compare & pull request” next to it.”
That’s no longer accurate. It doesn’t say “Your recently pushed branches”
It looks like this:
—————————————————————————————————
11
Trac says
“ • To provide a patch by sending a pull request. Claim the ticket when you start working so that someone else doesn’t duplicate effort. Before sending a pull request, review your work against the patch review checklist. Check the “Has patch” flag on the ticket after sending a pull request and include a link to the pull request in the ticket comment when making that update. The usual format is: [https://github.com/django/django/pull/#### PR].”
But the `pull_request_template.md` for GitHub has
“- [ ] I have checked the “Has patch” ticket flag in the Trac system.”
So I was left like which do I do first: the PR in GitHub or the patch thing in Trac? Obvs didn’t think it mattered as long as I did both but process is clearly important so trying to do the right way. What I decided: Ultimately I didn’t have pull request ID # (obvs because it’s impossible to get that before actually submitting the pull request) which means I didn’t have the link desired for “Has Patch” think in Trac so what I did was not check the box intending to do it right after which then resulted in:
Warning: Incorrect Trac Ticket Flag
The referenced ticket ticket-37093 does not have the Has patch flag set in Trac. This flag must be checked before a pull request can be reviewed.
What to do:
- Open the ticket at #37093 (Adjust GitHub PR description template + bot check error emoji) – Django.
- Scroll down and check the Has patch checkbox on the ticket.
- Save the ticket.
Which is not shocking of course just more like feeling — “yeah, I know I have to do that, and I’m already about to do that, but I just couldn’t do it before actually submitting the PR if you also want me to include the PR link in the Trac ticket”