Skip to content

Conversation

davidjb
Copy link
Contributor

@davidjb davidjb commented Nov 27, 2020

This change helps a contributor identify the branch name without having to click over to GitHub.

The previous documentation wording used "main", which could be interpreted as the branch name, particularly given recent shifts in terminology of primary branch name to main.

This change helps a contributor identify the absolute name without
having to click over to GitHub.

The previous documentation wording used "main", which could be
interpreted as the branch name, particularly given recent shifts in
terminology of primary branch name to ``main``.
@felixxm
Copy link
Member

felixxm commented Nov 27, 2020

Thanks for this patch, however I don't see much value in this change. We can change name of our main development branch in the future and the word main will still be valid.

@felixxm felixxm closed this Nov 27, 2020
@davidjb
Copy link
Contributor Author

davidjb commented Nov 27, 2020

@felixxm The patch intends to help the reader identify the name of the development branch -- which doesn't get covered in the documentation. The git clone command implicitly figures it out for you, but someone who needs the explicit name (in my case to know which branch to rebasing on) - needs to go and load the GitHub URL, then read the page (click the branch button) to learn the default branch is master (and not any of the other branches stable-*).

Not hard to do, of course, but explaining it on the official page would fill that gap, so someone doesn't have to go looking. Django thankfully only has master and stable-* branches so the answer is clear enough, but again, one has to go looking when the page could just tell you. A small clarification of this PR's nature would help the reader understand that master is the development version and not something else (such as main, if read literally).

@felixxm
Copy link
Member

felixxm commented Nov 27, 2020

... which doesn't get covered in the documentation.

That's not true, it's already described in many places, e.g.:

I don't see any point in using the branch name in the docs about "Installing the development version". If you want to contribute to Django, I would recommend checking "Contributing to Django" docs.

@davidjb
Copy link
Contributor Author

davidjb commented Nov 30, 2020

@felixxm I should have stated that the branch details don't get covered in this section of the documentation. The current instructions rely on the implicit default branch from GitHub being checked out through the clone process.

One could suggest that users installing the development version don't need to know the branch name, but there are situations where you end up on this page - as I did - when you need or it would be beneficial to learn dev branch name (e.g. knowing which branch to open a PR against, updating an existing clone of Django, rebasing a doc fix, clarifying if you should install master or stable-*, etc). By following the instructions on Contributing to Django for editing documentation, one ends up browsing like so:

  1. Contributing to Django: https://docs.djangoproject.com/en/3.1/internals/, which links to

    1. Advice for new contributions: https://docs.djangoproject.com/en/3.1/internals/contributing/new-contributors/, which also links to
  2. Writing documentation: https://docs.djangoproject.com/en/3.1/internals/contributing/writing-documentation/, which links to

  3. Installing the development version: https://docs.djangoproject.com/en/3.1/topics/install/#installing-development-version

My change is for users that arrive here via a flow similar to the above and is based upon my own personal experience - wanting to contribute docs, hitting that final page and needing to know the development branch name. The PR aimed to be minimally invasive - including this key piece of information for those that need it whilst retaining the same documentation.

Sure, it's easy enough to figure out the default branch name via separate means (or finding those other pages in the docs) - but this is the page you end up on when being instructed on how to contribute documentation. For note, the first link you've referred to (Working with Git and GitHub / Working on a Ticket) does provide the information, but you have to read between the lines because documentation isn't (necessarily) working on a ticket. The latter source code repository documentation link is perfect, but it isn't linked to from the Contributing page -- to find it, someone would have to either search or find their way to the Internals page, then scroll almost to the bottom to find the link. They're both valuable links, but just lacking the right wording or visibility in this context.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants