Related
On Github issues pages, how do you know which post contains the solution to the issue?
Take this page, for example.
The issue is closed, so we are to presume the problem is solved... yet this discussion thread (and many are much longer) seems to be mostly people talking back and forth in circles and it's very confusing to try to determine which post is intended or generally accepted to be the solution.
I was thinking it would be nice if the repo owner/representative could designate a post as what they determine to be the solution... with some kind of graphic... but I don't see that.
Ideally, if a pull request fixes an issue they would be linked by referencing the issue from the PR. For example, if a PR closes issue #123 the PR description would say closes #123 or fixes #123. You can also link them manually.
The PR would appear in the issue's "Linked Pull Requests" sidebar, and vice-versa.
For example, we can see that this PR is linked to this issue.
And from the issue we can see the linked PR.
In the issue, we can see activity on the linked PR as well as anything which mentioned it. A mention is a commit log or comment or issue or PR with something like #43878.
If the issue is closed for some other reason, ideally the person closing mentions why in a comment.
If people keep coming back to the issue and are confused, that may indicate the issue is not closed, or perhaps there is a related documentation issue.
In your example, we can see where the issue was mentioned in other issues.
And, sure enough, its referenced in issue #63056 and in PR #9 https://github.com/aws-amplify/amplify-flutter/pull/9#issuecomment-670038832. That information might help.
And we can see why the issue was closed, the change was intentional.
Unfortunately, the reason and resolution is buried in a comment. Improving the documentation may have been a better choice. That would have been done in a linked PR.
I was thinking it would be nice if the repo owner/representative could designate a post as what they determine to be the solution... with some kind of graphic... but I don't see that.
That would be nice. I don't believe Github has that feature. Posting it here is unlikely to reach Github. You could suggest it in Github Community or ask Support.
As a work around, one can make their final comment and then lock the issue so no further comments can be made. This would avoid burying the resolution. Then people would have to open a new issue if they really want to comment.
Or, one can edit the description of the issue to include a prominent reference to the resolution.
See also
Autolinked references and URLs
Linking a pull request to an issue
A year ago I have started an issue on github repository of a popular open source project. There wasn't enough data to fix it because bug was caused only by one closed source program. Recently I have stumbled upon other program that causes the bug and this one is open source. This should make it possible to fix the issue.
I have added new comment in issue providing new information, but it got no response for 10 days.
https://github.com/linuxmint/Cinnamon/issues/6253
I wonder if maintainers see comments on old issues in their notifications?
If they do did they discard it by accident or perhaps because in their experience most comments on old issues are useless?
Should I just edit last comment there slightly?
Will they see that?
Or what to do?
The good news is the project is not dead. Issues have been closed recently and PRs have been merged. Someone is watching the queue. The bad news is the project has over 800 open issues at this time which means they're probably swamped.
Open Source projects are typically run by volunteers, and that looks like a low priority issue. If you want it solved, do everything you can do reduce the work necessary to fix the problem. You've already given clear instructions on how to reproduce the problem, that's a very good start.
The single best thing you can do is submit a PR with a complete patch including tests. Be sure to conform to their developer guidelines. That project does not leave PRs open long. If you can't do a complete patch, take a stab at it and submit the PR asking for help. If you don't know where to start patching, make a comment on the issue asking for help with where to start.
Basically, do the work. If you can't do the work, show a willingness to do the work.
I posted a new issue on github for an opensource project. Shortly after posting I got a comment on the new issue saying "ya I agree and also [XYZ subject tangentially related to your ABC issue] needs to be fixed also".
On Stackexchange websites there is clear documentation specifying one topic per question: https://meta.stackexchange.com/questions/39223/one-post-with-multiple-questions-or-multiple-posts (maybe there is a better link but this is the link I found).
Where on github.com can I find something similarly authoritative to point a user to that says "it is recommended to post one topic per Github-issue"?
There isn't, and it doesn't make sense for GitHub.
Every person who owns a repo on GitHub can decide for himself how he manages the issues in his repo. Usually, you find such information somewhere in the repo. Sometimes a repo has a CONTRIBUTING.md file that details this. If it has, then it is linked when you try to open an issue. If it hasn't, look for this info in README files or in the wiki or the projects homepage.
But sometimes, you will not find it. And by that time, you start using common sense. Usually, the rule is to only discuss one issue per opened issue because that makes sense from a software development point of view. Its the only way you can label things properly, mark then done as properly, assign them to a person properly. And most importantly, it means that all info related to one issue is found at one place, making it easy to find at one glance.
Thus, virtually every contribution guidelines will state something in that direction, and when you can not find those explicitly, the general consensus and the expectancy is what I just laid out above.
What template do you use for comments on code commit?
One example of a template is:
(change 1): (source file 1.1, 1.2): (details of change made), (why)
(change 2): (source file 2.1): (details of change made), (why)
Ideally each change should be mapped to an issue in the issue tracker. Is this template alright?
Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.
You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.
Given these ideas, an example commit comment for me would be something like
Req3845: Updated validation to use the new RegEx validation developed in Req3831.
Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.
I prefix each paragraph with + - * or !
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
I don't think you should commit detailed description about what parts of the code are changed, because that's why every VC has diff :)
If you use a bug tracking system, include relevant ticket numbers.
You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.
Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).
Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).
I try to follow the same rule as for code comments:
Explain the WHY, not the HOW.
IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.
I try to keep my fixes in separate check-ins.
I don't use an actual template, but a mental one, and it's like this.
Issue - dev level summary of
issue.
The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.
Here's what I've seen used successfully:
Reference to bug number or feature ID
Brief description of the change. What was changed.
Code reviewer (to ensure you have one) unless handled by the checkin system.
Name of tester or description of which tests were run (if late in the process and you are being extra careful)
I use the simple technique described by Chaosben on the JEDI Windows API blog.
In order to get a fast view on the
changes made to a repository, we
suggest to write brief concise
comments starting each line with one
of these chars:
+ if you added a feature/function/…
- if you removed a feature/function/bug/…
# if you changed something
Doing it this way, other developers may find the desired revision much better.
First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.
I think that commit message conventions expected and used by git makes much sense:
The first line of commit message should be a short description
If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
In next paragraph or paragraphs describe the change, explaining why's and how's
Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.
There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.
Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.
If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change
There is a lot of conversation about commenting code, but how about commenting on check-ins?
I found this blog post:
http://redbitbluebit.com/subversion-check-in-comment-great-practices/
As the guy who is putting together the release notes, I am looking for ways to make that job easier.
Currently we defined our own scheme with <Begin_Doc>...<End_Doc> for anything that should be published to our software customers. But even for the internal stuff, I'd like to know the "why" for every change.
Every feature has a ticket/issue/bugreport/task/whatever-you-call-it, and the ticket number is always referenced in the check-in comment. This gives context.
I would advocate NOT using/overloading your version control system for this. I would suggest the issue tracking software as a better fit.
For one, it does not seem appropriate to have developers add all the context and duplicated information in a commit message that is already in a requirements doc or issue/defect system.
You can use a tool to gather the relevant fixes/issue numbers that are in the commit comments and then go collect those from your other repository, but I think it is a mistake to basically make your revision tool an external facing thing.
You need to define what the Source/version repository/SVN is - is it for managing your source files, or is it also for writing release note. I think it should not be overloaded.
We try to keep it simple: write one sentence describing the change that you are committing. If a developer needs two or more sentences to describe the commit, then perhaps the commit is two unrelated pieces of work. When commits like this end up in version control, then it is difficult to revert fixes in isolation.
Another piece of information that we like to include in our commit comment is the defect / feature number that the commit fixes / implements. Not all work that we do is related to a defect in our issue tracking system, so this is not compulsory.
One last piece of information that we put in our commit comments is the name of one code reviewer. This is the person who did a sanity check on the changes before the commit takes place.
I recommend functional comments. The comments should give a summary of what was changed. If something was changed, and why. Every commit should be explainable, if you can't explain it clearly, you probably shouldn't be checking it in.
The most important thing to remember when using source control logs is they are there to determine when and what was changed. The more functional, and detailed the better. commits should be made in bite size pieces, that can be explained with bite size comments.
My personal preference is this style:
UPDATED the error logging system.
Added a legacy error parsing routine using regex to get the legacy error codes.
Changed the text in the database error messages, to correct misspellings.
Removed commented out sections of code, because they were not used any more.
The key is what are you going to do with the comments. If you're creating release notes, then you can do as you suggested. However I would recommend instead you keep track of release notes somewhere else, such as in a project management or bug tracking tool.
As for developer related comments, we've generally asked people to explain what they're doing, a one sentence explanation. It doesn't need to be too formal, mainly because if it is people will push back against it. Plus, if you know who did it, and you have a quick comment, you can generally trace back the issue and find the person.
As well, if you use a tool like FogBugz, you can link an SVN checkin to a case number. Which means that you can look up the case to get the full discussion, comments, screenshots, etc. Which is much more information than you could ever enter in a checkin comment.
Agree with Remembrance, but you should also write a little bit about why you implemented the change /bug fix the way you did.
If you belive in checking in often, you should also include TO DO's in order to make it possible for one of your co-workers to complete the task.
Making my changes small helps: I can provide detailed descriptions of my changes this way.
The checkin comments should be the information that a developer wants: this includes refactorings, motivation behind the code, etc.
On our projects we always advocate providing some detail to what a commit is about and to assist in not having to duplicate information like the problem we use Trac and have our repository integrated. The advantage is that you can then reference the issue ticket in the comment and only state the resolution or steps of work carried out. Trac then automatically links the reference number to the original issue number and applies your commit message as a comment to the issue. Then when you want to see what has been done you can simply read the issues within Trac and have full context.
With regards to release notes we have found that taking the list of issues within a release and using the commit information as a basis for the comments has worked fine. Generally you will not have release notes that have the raw commit messages in them as your clients do not really care about every little change or even the level of detail that may be included in the comment. So you would normally need to do a fair amount of editing to highlight the main changes and bug fixes implemented in that release.
I would say to try to follow a changelog style. The first line should be a short summary, and include the issue/ticket number (if any). This should possibly be followed by a blank line depending on how your VCS handles multi-line commit messages, then a fuller multiline description. I would say it's unreasonable to impose any strict formatting since it will discourage frequent commits, but so long as the important commits (the ones closing issues, or major changes) are done this way you should be ok.
If you use something like Trac or roundup + svn integration, it can pick out issue numbers from the commit messages. I would always put these in the first line since they're so useful.
Edit: Given that this is by far my most downvoted answer, I think it's worth emphasizing what's hidden in the last paragraph: I'm a sole proprietor. I have 100% ownership of these projects and do not work with other developers. In a shop with more than one developer, everything I'm saying in this answer may be completely inapposite.
I subscribe to DRY here as in all things.
I almost never add a comment to my commits. A comment is almost always repeating myself. The answer to the question "what changed in this commit"? is almost always in the diff.
When I'm looking at a file and I ask "what the hell happened here?", the first thing I do is look at the diff with the previous rev. 90% of the time the answer is immediately apparent, either because the code's self-evident or because there was something not self-evident that I commented in the code. If it's not, I correlate the rev dates of the file with the bug-tracking system and the answer is there.
This always works. It sometimes requires a little investigation to figure something out, because I didn't comment my code adequately. But I've never been unable to find the answer fairly quickly.
The only time I add a comment to the commit log is when I know that a diff isn't going to help me. For instance, when I sort a class's members: the only thing that a diff is going to tell me in that case is that something very big happened. When I do that, I commit the file as soon as I've fixed it. There's no appropriate place to comment a change of that scope in the file, so I add a comment to the effect that the only change in this rev is reordering the members.
("Why wouldn't you comment a change like that in the revision history at the top of the file?" you might ask. I don't keep a revision history at the top of my files. That was a scary, break-the-habit-of-a-lifetime change to make, and I've never regretted it for a moment. The revision history is Subversion.)
If I didn't have 100% ownership of the project, it might be different. It might be too hard to correlate commits with bug fixes. It might be too hard to train other developers to code to a style that makes it possible to rely on version control effectively. I'd have to see.