Document references to PRs and Issues

[dmethvin]

As discussed in the Core meeting. Since Core has changed to using GH Issues we want to change our ticket references to make them clear. We're going with gh-xxxx for Github tickets and trac-xxxx for older Trac tickets. If this doesn't end up in Contribute we'll find a place for it in the core docs.

[scottgonzalez]

http://contribute.jquery.org/commits-and-pull-requests/#references

[arthurvr]

I know that will be nearly impossible, but my only opinion on this is that we should try to be consistent across all projects. Inconsistency makes it hard for cross-project contributors, as well as for new contributors.

[dmethvin]

That ship has sailed. Many of the smaller jQuery projects already use #xxxx to indicate Github issues, and if you're using GH issues from the start on a project it just makes sense to let Github help you out. Although it will find gh-xxxx in commits the online editor only recognizes #xxxx for example.

[arschmitz]

@dmethvin I'm not so sure thats true all projects were going have switch to match the style guide on contribute @scottgonzalez linked to. This says it should be gh- for anything on github. We had TONS of discussion to settle this style in the mailing list. This was decided because trac only allows # where github allows a github specific delimiter. So it seems like there should not even be a need for core to switch anything? if # is only trac as the style guide says and # was historically only used in trac this should be very clear already if the we just use them the way they are already documented.

[dmethvin]

We're definitely not forcing all projects from the jQuery Foundation to do all things the same way. If that were the case we'd all have to agree on a bug tracker for example. I opened the ticket to document the difference on this site for Core so people would know about it.

On the gh- point we're keeping that for core but switching to trac- for the now-legacy Trac tickets to be clear that we're not talking about Github. If we don't do that we'll end up with ambiguous references in our commits, see this discussion. Removing the commit hook prevents the references from being inserted into Trac but doesn't avoid the ambiguity when reading a ticket, unless you know about the bug tracker change and when it happened.

[jzaefferer]

The document Scott linked to says "Always use "gh-xxx" for GitHub issues", which, for example, QUnit completely ignores. We use #xxx references for issues and PRs.

I'm fine with adding project-specific exceptions to that document. I could also look into extending commitplease to check for specific issue reference prefixes, provided via package.json along with the components list.

[scottgonzalez]

Listing lots of exceptions will just make the documentation harder to read through and more daunting for new users. If there are going to be lots of differences, we need to move the information into the individual projects.

[mgol]

I think we should strive for uniformity accross projects. It might be hard to remember about specific rules but if commitplease checked the style of references, it could be taught to forbid #. It'd make it easier for outsiders for contribute.

trac-xxx is an exception since Core switched bug trackers but most outside contributors don't need to know about Trac as there are no open tickets there so it's mostly just for us.

[scottgonzalez]

Except that jQuery UI uses Trac.

[mgol]

Except that jQuery UI uses Trac.

Yes, I meant Core Trac, i.e. most contributors won't need to know that core uses trac-xxx to denote old Trac tickets. jQuery UI can continue using #, it'd be forbidden in other projects. In this way the divide is clear: # for things outside GitHub, gh- for things inside GitHub. If a project doesn't go behind GitHub (like Core or QUnit), # could be forbidden by commitplease.

Idk, is this too convoluted?

[arschmitz]

@mzgol if i understand correctly this is essentially whats already on http://contribute.jquery.org/commits-and-pull-requests/#commit-guidelines?

[arschmitz]

@mzgol worth noting you cant forbid it entirely or it breaks cross project references like [user]/[repo]#xxx which cant us gh- however thats a github specific format anyway so it is not ambiguous.

[mgol]

@mzgol if i understand correctly this is essentially whats already on http://contribute.jquery.org/commits-and-pull-requests/#commit-guidelines?

Yes, pretty much. We could just enforce not using # in projects using the GitHub issue tracker via commitplease, taking into account the restriction you mentioned in your second comment.

[dmethvin]

So is the consensus that no change is needed here and we'll just document our project-specific difference in our repo? I'd be good with a check in commitplease for use of #NNNN in tickets if that makes sense.

[jzaefferer]

For anything related to commitplease, an issue over there would be good, a PR even better.

[arschmitz]

@dmethvin there was additional discussion in #jquery-dev based on that I don't think there is any real need for project specific differences if @scottgonzalez can make the change he thinks is possible to trac which will also avoid future issues in ui.

[dmethvin]

Created the other tickets.

[scottgonzalez]

We can use InterTrac and have a reference back to the same Trac install; it's definitely not how it's supposed to be used, and would result in redirects for every link, but it would make it possible to have trac:#9000 or ui-trac:#9000 references. This is really intended for things like bugs.jqueryui.com having a core:#9000 (or similar) reference that links to http://bugs.jquery.com/ticket/9000.

[dmethvin]

I guess it's a question of which will be the most obvious and be the least likely to have link rot. If it turns out the Core Trac setup doesn't ever get migrated we can just link to the static wayback pages, honestly.