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
Do you get many issues that don't use your template because people go to /issues and click the new issue button? When I create an issue with a project, I typically don't a link in readme.md.
You could combine it with the new feature and put a warning message into the default box saying to click one of the links in the README in order to get an issue through.
It's not that the link isn't in the right place. It's that regular old users like me are familiar with the Issues -> New Issue workflow, and will continue to go right to that whenever we want to create an issue since it's a guaranteed way to create an issue.
Doesn't this inadvertently give users access to something they might not otherwise have? That is, the ability to add labels on issues. Might not really be a security concern, but not really desirable behaviour either.
I don't think so, it seems like its just a link to what you can see within the UI anyway and simply pre selects it for you. But I am by no means an expert on it and it is pretty simple to experiment with if you want to give it a try
https://developer.github.com/v3/issues/#create-an-issue gives a bit of list of things that can be set, when using it as a link title isn't required. I can't for the life of me remember where I first saw it so I am pretty sure someone else deserves credit!
I think it makes sense to have a difference in meaning between "I want to be e-mailed updates about this" (subscribe) versus "I think this is important/valuable/necessary" (star/vote).
Devils advocate: if you think it is important, then why don't you want to know when it's fixed?
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.
Knowing when it is fixed/closed is very much different than getting emails about every single comment going on about that issue.
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.
- 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.
> Devils advocate: if you think it is important, then why don't you want to know when it's fixed?
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.
I don't think showing number of subscribers is a good selection of if that subscriber supports the issue. It could just mean they want to see what's going on before they weigh in.
I watch a lot of repos, therefore I'm automatically subscribed to all and new issues, that'd show me as supporting everything.
I'm referring to people who explicitly subscribe to a given issue. It's true that this would not allow people watching a repository to explicitly register their interest but I think the percentage of interested parties who are watching a repository is quite low. (GH could estimate this by checking +1 comments on issues for watchers.)
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.)
I agree that starring or voting seems to add more weight than the current subscribe mechanism. However, I think if the presentation of the subscribe UI and the subscriber information is changed, this is a solvable problem.
I think that would probably frustrate users more than anything. Positioning the subscribe option more prominently (along with the number of subscribers) might have the desired effect.
Eh, I don't like getting spammed with notifications when I'm subscribed to a popular issue. Maybe that will be less of a problem with fewer people posting +1 comments, but still. I wish I could just get a notification when the issue is closed.
Sure, but what if I don't care about being notified of ongoing discussion for an issue, and instead just want to be notified when it's been closed, or maybe a pull-request has been submitted?
The problem is that there is currently no way to see the number of subscribers on an issue so it can't be used as a signal of interest. I don't understand how a suggestion to change user behaviour can be proven false because the undesired behaviour exists before the change.
I've thought long and hard about the "voting" mechanism, and I am really, really torn. Tons of people writing "+1" is a very aggressive voting mechanism. It is noisy and loud, which I think is a desirable trait for some issues on open source projects. There are lots of projects with awesome developers that listen to their users and are commendable souls. There are also lots of projects with developers that don't give a shit about what their users want. Yes, yes, "if you don't like it, write your own", but that simply isn't possible for I'd say most projects out there. And so the +1 comments "voting mechanism" has spawned what I call "the new tyranny of 'locked to contributors'", which itself is a pretty good indicator of the kind of developers running a project. There are projects out there which have issues with huge long chains of +1 comments and enormous bug bounties on BountySource, and for whatever reason, the developers have chosen to ignore the issue, eventually locking discussion to contributors. For me, this is a huge indicator about the developers and the project, and I will generally avoid it if at all possible. The reason I'm on the fence is because it will remove this big, loud indicator when there is a star or vote button or whatever. That is much quieter and easier for the developers to simply ignore -- and of course, that's their prerogative, just as it's mine to not use or contribute to a project for the same reason. Anyways, this is my thought process on the whole voting idea.
But none of that matters for either kind of developer, does it? For the awesome ones it's just noise, and the bad ones will just ignore it.
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?
I didn't say anything about it mattering to the project's developers. I said it matters to me because it's an excellent indicator about the quality and personality of the developers working on a project. It helps me to avoid like the plague some janky project where some popular issues languish in 'locked to contributors' when some other project listens to users. Most importantly, when the time comes that I will want to contribute to a project I use by submitting bugfixes or PRs to support other functionality, I know what the climate is like. I'd much rather know to avoid a project before I even decide to use it than six months into embedding it into my production workflow.
Now I actually start to worry. Did anybody here ever have the problem of making people happy with a software project?
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.
I'm confused, probably because of too much variable usage in your comment.
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?
They implemented the wrong thing though. And now you ask "What's the right thing?" to which I will say "Nobody knows yet"
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 agree. At least they made a way to separate GitHub stuff:
>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
Yes. Yet it's a bit weird in case .github folder is used. Will they support a .bitbucket, .gitlab, etc. They could have used a more generic name like .contributing, but this increases the risk of name collision.
Something only belongs in the same branch as the code if it should be forever tied to the same version as the other files in that branch.
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.
GitHub is always going to use the issue template that's on master, not the template from whichever version you happen to have checked out on your machine.
Current file on master to boot. But what makecheck is saying is that only what's in current master matters, not what's in `feature/something-here` or in a commit tree from last year. So shoving it in the repo isn't really a good solution.
No it's not. I can use the README outside of github as a guide on how to do things with the code. Contributing can define a style guide so we're all on the same page code wise. LICENSE for distribution, Makefile, package.json both are required for the code to work correctly... issue_template.md is only useful in a repo on github.
Last time I checked the Wiki was a separate, parallel repository, so a precedent exists. I'm not sure where it fits in your classification (code/documentation or project management).
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.
I totally get where you're coming from. An extra file in your repository is quite the burden. This template file is the straw that broke the camels back. It should be removed.
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.
Except that CONTRIBUTING.md and README.md and LICENSE are all typical files found in a repo that are independent of GitHub. If I push this repo to bitbucket or gitlab, the same stuff is just as important. But `issue_template.md` and `pull_request_template.md` is only dependent on github and is clutter in the repo. Sure if gitlab or bitbucket have these features and use those names, cool it translates to those services too. But it doesn't matter to the code itself.
Ideally both of those files should be under a `templates` section in the repository settings tab.
Besides what joshmanders said, I would argue a change in license is usually caused by a change in code and would also mark historically when a project went from X to Y. A README will probably also need to change with new code changes. As for having contributions file. I'm not really for that, but not against it either.
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.
If gitlab stored its issues and wiki on a separate branch of the main git repo in some format I can still read when I decide that some other server (github, bitbucket or maybe just plain git), I would actually use those features. Right now they feel like completely unnecessary lock-in, so I’ll stick with Doxygen in-repo bugs/issues/todos and documentation.
Geez. I would hope so. Too bad it took them the better part of half a decade to listen to users. I've already moved a number of my personal projects to Gitlab, Bitbucket or a self-hosted Gogs installation.
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.
The template is more for actual issues with the software than to-do lists/user grievances, the latter of which I see used more frequently in GitHub Issues. Maybe it's time to separate GitHub Issues into Issues and Discussion.
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.
I don't agree. I think this is a great step into encouraging users to follow a format when submitting issues. It would make it easier to add tags to these issues as well. Any other discussion can be submitted the same way, you'd just remove the template and start typing.
I asked Craigslist to do this years ago for the "for sale" sections, so that people included the number of doors on a car, the color, etc., and the kind of heat in an apartment, and so on. Such a simple thing, and would make searching so much better, and the service in general better.
Craigslist has dedicated form fields for a lot of those things, which can then be used with search filters. The problem is that they aren't mandatory, and most users don't fill them in.
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.)
Allowing sellers not to fill out additional information that they easily could provides a useful signal to buyers about how well the transaction is likely to go.
colinodell posted that before the blog announcement when we only knew about issue_template.md. It was to point out that you can do this with pull requests as well, not that it was case insensitive.
Would you also like for it to ensure that all check boxes in your template are checked prior to submitting? Ask the user to please submit to a lie detector test? I think this is a completely reasonable solution to the problem and will cover the 99% case.
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.
Users will find a way to subvert your desires in any case. IMO it's better to let users easily ignore your expectations and set up a bot to automatically close such issues with a comment explaining why. Much better that way than having a bunch of correctly formatted garbage.
How does that work with branches ? Is there a master branch required to have this file, what if project doesn't have master branch ?
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.
You can set the default branch [1] which will be shown on your repo's page and used by default for pull request.. I guess it should take the templates from that 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.
The problem I have with this is, I don't want a template for the comment a contributor leaves on a PR; I want to display a message to them before they submit a PR. It's not a standard way to display messages, requiring users to read editable text (that has no clickable URLs) and then delete that text after they read it and submit.
It’d be interesting if it’d provide a separate input box for each section of the template – maybe even a graphical editor for lists if the template specifies a 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.
What's the use case of people seeing it? GitHub should be adding it automatically; issue reporters aren't copying-and-pasting the template manually. The only people who should really need to see the file itself are maintainers (or fork maintainers), unless I'm missing some use case.
I'd like them to choose a folder name that isn't specific to a site. .github would look silly on hit lab but I like the idea of having a serrated folder.
Trying to use a GitHub only feature on GitLab would look equally silly... This is very much a GitHub specific implementation. It makes sense for it to be identified as such.
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.
I wonder why they have restriction based on file extension in place, it's just inconvenient that you have to rename .patch to .txt only for the UI to accept it.
If you've ever managed a big OSS project you'd not think of it like 'enterprise' bureaucracy but a time safer. If OSS users can't even be asked to fill out a minimum amount of information based on a template, then I have zero interest spending my free time helping out.
Yes, OSS users have a very wide gamut — for everyone who sends a pull request with good troubleshooting and a patch, there must be half a dozen people who click New Issue, submit minimal information and, if you're lucky, come back a couple of days later and acknowledge that the real problem was a hacked up local install, using a 5 year old version of a core dependency, etc.
I have this same feelings, but after thinking a bit, you'll see this is not bad. For big projects it will help an enourmous lot, but small projects don't need to use this, and probably will not, so it is still good.
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...
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