Issue and Pull Request templates
github.com
github.com
You can then add it as a simple href to the readme.md.
It also means that you can have multiple templates depending on what a user wants to do, just by having multiple links and changing the content of the `body` parameter.
Simplest way to get going on this is to use http://urldecode.org to write the markdown you want and then hit the encode button, take the result and add it after `body=`
We also use it to auto-assign labels using `labels=` in the URL
Next item, be able to star issues.
That would help a lot and we are able to avoid +1 comments.
I watch a lot of repos, therefore I'm automatically subscribed to all and new issues, that'd show me as supporting everything.
I think the advantage of using subscribers is simplicity. Adding another feature that is arguably similar to the existing subscribe complicates things.
A concerned user will feel like they are adding more weight by "starring" it (or "voting" / "+1"ing it) than "subscribing" to it. Even if they really mean the same thing, ie adding to a counter and notifying on updates.
(And I doubt it's a good idea to separate these functions, even if some people will protest they have a corner case where they would want to do one but not the other. It adds unnecessary complication.)
Starring instead of subscribing is basically the issues equivalent of "Hire, but not for this team". If you limit it to people who care enough to subscribe, you only get the people who actually are invested in it, and avoid the people who think it should be fixed but who don't actually need it to be.
- Receive all emails about this bug except comments - Only receive email when this bug is closed
There's also an "this bug affects me", which records that and then gives you the option to subscribe to either of the two options above. Seems like a happy medium.
> why don't you want to know when it's fixed?
Starring issues (as in Google Code Project Hosting) meant "I want to see this getting fixed" and subscribing issues on GitHub does not show anything like that. If I am not mistaken, you only see a list of people “participating” to an issue, you don’t get to see list of people getting emails about that issue.
Because I've implemented a workaround (after spending a few hours tearing my hair out wondering why the straightforward version didn't work) and I may or may not ever remove the workaround, not to mention I might have dropped the project or changed company entirely by then.
I may or may not care that it's fixed (though I probably do in the chance that I have to do this again in the future and have by then forgotten about the need for a workaround), but I do want to notify somebody that I have hit that issue and have had to work around it, and that it would be nice if future users didn't go through my own experience.
e.g. "Did you mean to subscribe instead?"
Why does it matter if it is a simple counter? It'll tell you exactly the same information, with a lot less cluster. And it'll help people reading through issues that are littered with it.
Personally I think having a +1 counter is a win-win solution. And I detest all the +1 comment spam in issue threads, it is noisy and doesn't contribute to the conversation.
Until then, why not create a bot that deletes all +1 posts but edits the main post with a counter of +1s?
The usual complain goes like this "You need to do X because I want to be able to do Y." In the complainers mind there is the untested idea that having X will enable him to do Y which solves his unspoken problem Z that he isn't even aware off. The thing is, at this time you don't know Z. You don't know if Y is really solving Z. And you don't know if X is really solving Y. And neither does he. But if you want him to use your tools he doesn't need to worry about that as much as you.
What happens if you just go like "Okay, user wants X, here is X!" is that the users will continue to complain (maybe even more) because Z is still not solved, and because there was no testing and planning involved X is actually creating another problem Z2 that nobody had before. At least that's my experience with an open source project I managed for about 3 years.
What I found actually needs to happen is to discover Z and to discover a way to solve it in the context of the project (which other people may not be as aware of as you are), and with an at least minimized chance of creating more problems. Then this actual solution needs to be sold to the users, because they are not aware of Z, so they think they don't care that you solved Z. But only after doing all that people will stop complaining (not even remembering that there was a problem and how much pain you went through to solve it of course).
Hope that makes sense and explains why I start to worry now, when everybody starts cheering. What I hoped would happen is that you don't hear much about the suggested changes, some other changes happen a few weeks down the road, and then the complains stops without anybody noticing. A success would be that you don't read about github anymore after 1-2 months. People cheering and github saying "Hey we did X" is a really bad thing.
If one or more of the variables were GitHub, or issue templates, then:
Don't be concerned. The user community listed grievances with some missing functionality. GitHub listened and implemented some. In this case without changing functionality for people who didn't want this. (So the person who likes the URL method can stick with that.)
Good on GitHub implementing something to help their users. Isn't that what we want? Or do you want then to ignore their community?
X = proposed solution by users, Y = guessed problem by users, Z = actual problem nobody knows about yet.
The proposed solution is only maybe a solution to the proposed problem, probably not. Because users won't go and try things out and then come to you and tell you what they found out. They have a feeling in their stomach and they tell you about it. The same goes for the problem they tell you about. It's maybe not their real problem but a symptom of another problem. You need to go and solve the actual problem.
Example: Patient (=user) goes to doctor (=github) and says "I have a headache (=Y), please give me some pills against headaches (=X)". Well, headaches can be because of lack of sleep, lack of water, too many worries, an infection, or maybe even cancer. Now the doctor's job is to figure out which of the actual problems it is. He talks to the user, does some analysis and figures out the actual problem is lack of water (=Z!!!). He tells the patient to drink more water (solving Z, Y is indirectly solved, and no word about X). Patient goes home, drinks more, is happy, doesn't come back to the doctor.
I personally prefer this non UI/Github specific approach.
As to whether or not I want it tracked/versioned, that is completely outside the workflow for versioning in code in a repo. You can maintain a "version" of this separately ala Wikipedia's edit history, or even just have a hidden separate git repo for these things if you must use git. They already have this with gists.
With lint configs or npm configs you can argue that changes to those would affect code, which would require them to remain in sync. But what is the point of this new issue_template.md as part of the git repo? It's not as though there will be any significant time where a code change necessitates a change in how issue templates are made.
This feels like a bad hack. Like they saw CONTRIBUTING.md and thought, "well might as well just keep going" and added issue/pr templates.
But why stop there? Let's also remove the README.md from the repo. It can also have it's own independent revision history. Maybe they should also add a feature for managing the LICENSE file for you.
/sarcasm
Ideally both of those files should be under a `templates` section in the repository settings tab.
The problem isn't that it's just one file (actually 2 if you're counting pr templates), the problem is we're just going to continually get this pollution of the project because it'll become "acceptable." Slippery slope and what not.
I mean at this point why is the wiki in it's own space and not git versioned? (Put it in github-wiki folder!) Why have separate gh-pages as well? (Just stick them in github-web folder!). Just shovel everything into one git repo. Don't forget the .githubconfig file in case you want to programmatically config a repository instead of going into it's options menu. And on, and on, and on.
I understand your overall point, but as a slight aside the wiki is a git repo: https://help.github.com/articles/adding-and-editing-wiki-pag...
Suppose I check out a project using a version from a year ago. Project maintainers would certainly not expect me to use last year’s issue template, last year’s preferred pull request layout and last year’s rules for contributing! That is why shoving things into the "git" repository is a hack.
Having this stuff under some revision control is useful but it could be a separate, parallel repository. Frankly, I think everything for project management should be in one repository, and everything for code and documentation should be in another, and GitHub should be able to use files from both to present a project site.
I'm guessing there isn't an "export issues" feature so the above point is moot.
I favour the portability.
I'm going to move this out of wikis and into SCM ASAP.
>If you're worried about the added clutter in the root directory of your project, we also added support for a .github/ folder. You can put CONTRIBUTING.md , ISSUE_TEMPLATE.md , and PULL_REQUEST_TEMPLATE.md files in .github/ and everything will work as expected
I hope that all repos don't start using it just cause it's there.
So there is more to come
I've still got reasons to stick with Github for some projects, but it's not the new hotness it used to be.
$10 says the next new feature is voting on issues.
EDIT: Missed the fact that the feature is opt-in by the repo owner, which makes things more expected depending on the nature of the repo. Although now thinking about it, the separation is still not a bad idea.
This is a great step forward and I'm excited that GitHub is doing this.
The link was changed to the GitHub blog post sometime in the past hour since _ikke_ commented.
The side effect of this is that if you use the search filters, you risk missing out on a result which matches your criteria but lacks the metadata. (Craigslist doesn't have an option to search for only Blue AND Unspecified, so there's no good way to just hide the explicitly non-Blue cars.)
I do however feel like it's a temporary and half-hearted quick fix. If it were possible to add custom fields to the issue tracker, they could be used to sort and filter issues. They wouldn't have to be required, but maybe if you don't fill them in, your issue would be labeled "incomplete".
Since they're now asking people to go ahead and add a template file to their repos, it will make it more inconvenient to change this later.
I think the concept of having a file in source code is flowed for DVCS unless you have so called "source" branch that you can define that is a default source of such information.
[1] https://help.github.com/articles/setting-the-default-branch/
>If you're worried about the added clutter in the root directory of your project, we also added support for a .github/ folder. You can put CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in .github/ and everything will work as expected.
I hope they address the other issues as fast as this one. Rating system is the next one on my list.
> If you're worried about the added clutter in the root directory of your project, we also added support for a .github/ folder. You can put CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in .github/ and everything will work as expected.
So you can put them in `.github/` if you don't want them in root.
It would be nice if they used a specific branch a la gh-pages so that everyone's Git repos don't have to be polluted with GitHub specific files.
Newsflash: You don't have to use these for your projects if you don't want to.
two years and that's what we get? meanwhile my bigger diffs are still garbage. and we have to use other companies to have a simple agile board... and don't even get me started on decent branch management and rebases...
sigh. really hate that my employer buys that