Add WordPress Git & GitHub mirror docs to https://wordpress.org/download/

[netweb]

Currently Subversion docs are linked on the ​https://wordpress.org/download/ page.

I think we should add Git and possibly also GitHub mirror details with basic instructions as the current SVN page does.

​https://wordpress.org/download/svn/
​https://wordpress.org/download/git/
​https://wordpress.org/download/github/

The other option is to combine them all into a single page

[nacin]

Please not GitHub until we straighten out the hash hell there.

[iandunn]

+1 for adding develop.git.wordpress.org instructions.

@matt, is that ok with you?

[matt]

Yes I'm okay with this -- rather than another menu item, let's redirect /download/svn to a new page that covers both.

[iandunn]

@netweb, that part of the site isn't open-sourced yet, but if you want to write up the content for the new page then I can handle merging it.

[netweb]

Replying to matt:

Yes I'm okay with this -- rather than another menu item, let's redirect /download/svn to a new page that covers both.

How's /download/vcs sound? Maybe /download/versioncontrol though looks kind of clunky after typing it :/

This is what I thought of for the combined page, add the Git ref's next to their SVN counterparts with updated references linked to each SVN/Git handbooks at their respective sites:

<p>And this will output a line-by-line description of all the changes in a format that makes it easy for us to incorporate (<a href="http://svnbook.">SVN</a>/<a href="http://git-scm">Git</a>):</p>
<p>SVN: <code>svn diff </code></p>
<p>Git: <code>svn diff </code></p>
<p>You can output this to a file (.diff or .patch) by using <a href="http://www.linux.com/article.pl?sid=04/05/02/1758211">redirection</a>:</p>
<p>SVN: <code>svn diff &gt; my-patch.patch  </code></p>
<p>Git: <code>git diff &gt; my-patch.patch  </code></p>

[iandunn]

Maybe something like /download/svn-git would be more better? It'd be more specific and familiar than "VCS"; I'd worry that a lot of newer devs wouldn't recognize "VCS."

My first instinct would be to have separate sections for SVN and Git, rather than mixing the two. That way visitors could focus only on the parts that are relevant to them, and ignore the rest. That'd be quicker to scan, and would avoid people being confused about which commands to use.

It'd also give us a better opportunity to highlight the differences between the two workflows. With Git it's important to stress the need to work on separate branches for separate tickets, generate patches with --no-prefix, etc.

Although, that makes me wonder if the page should even be discussing how to generate patches and whatnot. It is a "download" page after all, not a "contribute" page. Now that we have the Core Handbook, I think it might be better to just have an intro about the history of WP's VCS usage, and show very brief info of how to check out/clone trunk, then link to the Core Handbook for details on a full contributing workflow.

The Handbook would need a Git equivalent to ​the SVN page first, though, which would be really nice to have anyway. It could borrow some info from ​the Git page in the Meta handbook, but will have some significant differences because we have an actual Git repo for Core, rather than needing to use git-svn.

Thoughts on all that, everyone?

[netweb]

Replying to iandunn:

Maybe something like /download/svn-git would be more better? It'd be more specific and familiar than "VCS"; I'd worry that a lot of newer devs wouldn't recognize "VCS."

I was thinking ahead for when the GitHub hashes are fixed ;) Though /download/svn-git could still include GitHub as it is still Git.

My first instinct would be to have separate sections for SVN and Git, rather than mixing the two. That way visitors could focus only on the parts that are relevant to them, and ignore the rest. That'd be quicker to scan, and would avoid people being confused about which commands to use.

It'd also give us a better opportunity to highlight the differences between the two workflows. With Git it's important to stress the need to work on separate branches for separate tickets, generate patches with --no-prefix, etc.

Although, that makes me wonder if the page should even be discussing how to generate patches and whatnot. It is a "download" page after all, not a "contribute" page. Now that we have the Core Handbook, I think it might be better to just have an intro about the history of WP's VCS usage, and show very brief info of how to check out/clone trunk, then link to the Core Handbook for details on a full contributing workflow.

Agreed, so on the /download/svn-git page we'd only want: (With links to SVN/Git docs)

svn co https://core.svn.wordpress.org/trunk/	git clone https://core.git.wordpress.org/trunk/
svn update	git pull
svn status	git status

And leave the "develop" repo for the Core Handbook page? (and creating patches etc)

svn co https://develop.svn.wordpress.org/trunk

git clone git://develop.git.wordpress.org/

The Handbook would need a Git equivalent to ​the SVN page first, though, which would be really nice to have anyway. It could borrow some info from ​the Git page in the Meta handbook, but will have some significant differences because we have an actual Git repo for Core, rather than needing to use git-svn.

Likewise for the handbook https://make.wordpress.org/core/handbook/svn-git with the new Git changes added to existing SVN.

Thoughts on all that, everyone?

Not sure on the layout, keeping them separate or inline as per my example above kind side-by-side, anyway there really isn't that much html to add for either page so cutting and pasting to rearrange shouldn't be too difficult.

[nacin]

We could probably combine this with /source/ too, and then use /source/ as the primary.

[iandunn]

Replying to nacin:

We could probably combine this with /source/ too, and then use /source/ as the primary.

+1

Replying to netweb:

Agreed, so on the /download/svn-git page we'd only want: (With links to SVN/Git docs) [...]

Yeah, that sounds good :)

Likewise for the handbook ​https://make.wordpress.org/core/handbook/svn-git with the new Git changes added to existing SVN.

I'm guessing for the Handbook it'd be better to have separate pages, since there's so much content for each VCS, but the editors can decide that.

I guess we actually don't need to wait for a new Git page on the Handbook; we can go ahead and add the new content to /download/source, and link to the existing SVN page on the handbook, then come back later and add another link for the Git page when it's added. In the meantime, maybe link to ​the announcement post for the Git repo, or ​scribu's instructions for contributing with Git.

[iandunn]

@netweb, no rush, but when you have time can you grab the rendered HTML from /source and implement the proposed changes, then upload the new file here? That'll give me something concrete to merge.

[netweb]

Replying to iandunn:

Replying to nacin:

Likewise for the handbook ​https://make.wordpress.org/core/handbook/svn-git with the new Git changes added to existing SVN.

I'm guessing for the Handbook it'd be better to have separate pages, since there's so much content for each VCS, but the editors can decide that.

The Git handbook page has just been published by @jorbin: ​https://make.wordpress.org/core/handbook/contribute/git/

@iandunn Can you create the new page /download/svn-git and redirect /download/svn to it with links to the SVN & Git core handbook pages?

[iandunn]

​Updated in [dotorg12306].

I intentionally left out periods in sentences that ended with the Git URLs, to avoid people accidentally copying them, which would result in a failed clone.

[netweb]

Replying to iandunn:

​Updated in [dotorg12306].

I intentionally left out periods in sentences that ended with the Git URLs, to avoid people accidentally copying them, which would result in a failed clone.

@iandunn You should change the SVN URLs to be wrapped in code blocks so they are also easily cut & pastable

i.e:

• https://core.svn.wordpress.org instead of core.svn.wordpress.org
• https://develop.svn.wordpress.org instead of develop.svn.wordpress.org

Maybe include /trunk on each SVN URL so only /trunk is checked out and not the entire SVN repo?

i.e https://core.svn.wordpress.org/trunk and https://develop.svn.wordpress.org/trunl

[iandunn]

Those are good ideas, I put that on my task list. Not sure about an ETA though, since it's low-impact and not urgent.

[coreymckrill]

change the SVN URLs to be wrapped in code blocks so they are also easily cut & pastable

How about something like the above?

[iandunn]

That looks pretty good to me.

What does the dashicons-external link to? Does it open in new tab?

We might want to consider adding the checkout/clone commands, like:

• Subversion: svn checkout https://core.svn.wordpress.org/trunk
• Git: git clone git://core.git.wordpress.org/

That might make it easier for users who aren't familiar with SVN/Git at all, but it could also confuse people who use GUI clients, since they'd need to parse out the URL.

[coreymckrill]

What does the dashicons-external link to? Does it open in new tab?

It links to the SVN repo, not in a new tab. I included it because in the previous iteration the SVN URL was a link instead of copiable text. I would be fine removing it, but I do think it's useful to show people that they can look through the repo on their browser rather than having to do a checkout.

We might want to consider adding the checkout/clone commands

In this case, I would probably prefer to leave them as just the URLs for simplicity. People who want to know what the repo URLs are need to have a basic level of understanding about SVN/Git in order to do anything with them anyway, so they should know which commands to use.

For the same reason, my preference would be to leave off /trunk. Branches and tags are useful for some people, and checking out the whole repo doesn't take that long (unlike the Plugins repo).

[iandunn]

Replying to coreymckrill:

It links to the SVN repo, not in a new tab. I included it because in the previous iteration the SVN URL was a link instead of copiable text. I would be fine removing it, but I do think it's useful to show people that they can look through the repo on their browser rather than having to do a checkout.

I agree that's a useful feature. I think Trac offers a better online-browsing experience, though (syntax highlighting, AJAX folder expanding, etc).

Just linking to Trac could confuse some people, though, since the distinction between core.svn and core.trac needs explaining.

I wonder if something like this would be good?

The built WordPress source [...] can be ​browsed online, or checked out locally:

Subversion: https://core.svn.wordpress.org/
Git mirror: git://core.git.wordpress.org/

---

In this case, I would probably prefer to leave them as just the URLs for simplicity. People who want to know what the repo URLs are need to have a basic level of understanding about SVN/Git in order to do anything with them anyway, so they should know which commands to use.

Works for me.

[coreymckrill]

The built WordPress source [...] can be browsed online, or checked out locally:

Love it.

[coreymckrill]

Hmm, is there a way to link to the Trac browser for the built version?

​https://core.trac.wordpress.org/browser goes to the development version...

[iandunn]

Replying to coreymckrill:

Hmm, is there a way to link to the Trac browser for the built version?

Hmm, I don't think there is.

For the use case of someone casually browsing the code, though, is that distinction important? If we link to /browser/trunk/src/, then the user lands in a familiar spot (wp-admin, wp-includes, etc). If they're aware of the unit tests, etc and want to see them, they can just browse up a few directories.

It seems like just having the 1 link might be easier to describe in the paragraph too, rather than having to explain what each is.

[netweb]

Replying to iandunn:

Replying to coreymckrill:

Hmm, is there a way to link to the Trac browser for the built version?

Hmm, I don't think there is.

Yes, here it is ​https://build.trac.wordpress.org/browser

For the use case of someone casually browsing the code, though, is that distinction important?

I don't think so, if someone wants to view the "built" source code they can view the contents locally via wordpress.zip

[coreymckrill]

Here is a new iteration with links to the Trac browsers and other wording tweaks.

[coreymckrill]

Fixed in [dotorg13200]