Almost every issue needs a documentation subtask.
Many issues need a localization subtask.
Should documentation and localization issues have their own workflow (by issue type)?
Should each project have documentation and localization components, so that those issues would be automatically assigned to the component owner?
Should "Create Issue" screen have a checkbox "Needs documentation", which would create a documentation subtask with specific fields?
I agree, only create issues or subissues for work that occurs in parallel and needs a different assignee or due date or such. If the work happens in every case then build it into the workflow instead.
The other thing to be aware of is that whatever is entered in a field such as "Notes for Documentation" always needs human review before being sent to a customer.
I have a different understanding for working with JIRA. For me, JIRA helps me understand when I have to do something, what the status is, and when I'm done with it. When documentation and localization is every time necessary, I would not like to overflow my JIRA with all these sub-tasks everyone understands that they are necessary.
The only reasons, why these should be extracted as sub-tasks (and managed with a workflow) are:
You have normally a different assignee for documentation and / or localization, so you are able to assign that to a different person.
Their workflow is different, therefore you want to manage it separately.
I would not expect additional components for them, because when you want to isolate them, just have a custom field for it (or create a sub-task like work item for documentation and localization, don't know if that is easily possible).
I would not add that "Needs documentation" flag, because people that add issues often don't know if documentation is necessary. So no, I would not add them as sub-tasks, neither as additional flag, but explain everyone that documentation and localization is necessary. There should be ways to check that automatically, without any issue ...
And of course, you are free to add a documentation screen with additional custom fields. There you could document in implementing the issue what you have done about documentation and internationalization. So checking that these are empty, would replace the flag you have mentioned.
Related
General situation
We have a project on GitHub and in hosted.weblate in the libre plan.
The weblate project contains 3 components and a glossary.
Two languages are already completely translated and we use the continuous localization workflow.
There are some additional languages from the very kind community. However, these are not complete(d yet), so they cause problems in the front end (like showing no text or the plain string.variable.name).
What should be achieved?
We would like to have the incomplete languages only available after they are complete (at least have no empty strings). So they should be pushed only if either a manual flag is set/removed or at a certain completeness level. Is there a way or best practice on how to deal with that?
Ideas to achieve it (but no idea if this is possible)
An idea would be to only commit changes on languages, that have a certain overall completeness level. For the languages that are completed already we would ideally keep the continuous translation workflow. Also manual commits are problematic, since they would commit also the incomplete languages.
Is there a way to set a flag or achieve a .gitignore like behaviour for certain languages in weblate? When they are not empty anymore, we could of course manually activate the languages.
I've set up a translation project for Syncthing on Hosted Weblate, which was previously handled through Transifex. There was already some tooling in place which respects this completeness filter, and it was pretty easy to adapt to Weblate.
Basically we don't push Weblate changes back to the upstream repo, but pull them in through a regularly called script, together with some other housekeeping tasks like an authors list. The script checks the statistics on every available language and if the completion is above 95 percent, the language is added to a "valid" list, which the GUI uses to offer choices. Translations previously on that list drop off only if they fall below 75 percent completion.
In any case, the script downloads the most recent translation files and commits them to the upstream repo for archival reasons. When this happens, Weblate picks up the new commits and rebases its internal repo. That also allows integrating translation contributions from other sources easily.
It is currently not possible, but there is issue tracking this: https://github.com/WeblateOrg/weblate/issues/3745
I've been wondering is it possible to change the message that appears in the input field when you commit on Github. Refer to the picture below:
I like my commits to be as descriptive as possible and enjoyable to read. I want Github to suggest 📝 Create README instead of Create README.md.
When I search for the solution, the 'google search' shows irrelevant answers. Is it somehow possible?
Note: This does not answer my question.
If you can do this at all, it certainly won't be easy. The GitHub web interface is proprietary software that does not provide a setting for you to make this change. You might be able to create a UserScript in your browser using TamperMonkey (or similar) that detects the fields on the page and modifies them, but you'll have to write all the logic and then keep changing it whenever GitHub makes changes to their code.
Note that your suggested commit message that contains emoji is not actually more descriptive than their default message, in fact many people will find it less readable.
May be a well known question, but actually I'm asking this, because I'm not familiar with these tags.
I've seen similar types of tags in various Github projects, especially in their README.md. My questions are manifold regarding these:
What's the purpose of these tags?
How to generate them?
Is there any good practice or documentation that suggests what types of tags can be used or should be used in a project?
When a project can be determined viable using such a tag?
What's the purpose of these tags?
These images are provided by external services, often continuous integration services, and are used to show interesting information about the repository.
For example, the first badge you show in your example says that the build is "passing" (the exact definition of this will be build-specific, but it commonly means that the tests pass and nothing blew up during the most recent build).
The third example, coverage: 12%, is a code coverage report.
How to generate them?
Each service will have its own way.
The second badge in your example is from Scrutinizer, and unfortunately I can't find documentation about its badges. But most badging systems work by giving you a link for each project or job that you can use on your website or GitHub or whatever, and when a build happens the badge's appearance is updated accordingly.
The Travis CI documentation contains a good example.
Having answered the first to questions, I think your last two largely disappear. The badges that can be used are determined by whatever services you can find. The badges that should be used are entirely up to you.
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.