search

phetsims / tasks

General tasks for PhET that will be tracked on Github
MIT License
5 stars 2 forks source link

Standardize labels for GitHub issues #465

Closed phet-steele closed 8 years ago

phet-steele commented 8 years ago

Make all the labels across sim repos and tasks the same color and text.

ariel-phet commented 8 years ago

@samreid has suggested that multiword labels such as "high priority" are hyphenated "high-priority" "code-review" "master-checklist" and such

some other standard labels that should be on all sim repos "master-checklist" "high-priority" "medium-priority" "low-priority" "wishlist" "requires-kathy" "developer-meeting" "phet-io" "teaching-resources" "a11y" "i18n" "design" "code-review" "deferred" "phet-io-meeting" "performance" "licensing" "fixed-pending-testing"

*EDITED to reflect developer feedback

especially for searches it is important to have these all exactly the same, so please modify any existing labels to be consistent.

@samreid @mattpen @jessegreenberg @pixelzoom @jonathanolson @jbphet please chime in if there are any other standard labels you wish to add to this list or if you want any of the "boiler plate" labels removed or changed

Here are the boiler plate ones that come with a new repo:

labels

pixelzoom commented 8 years ago

Having to manage labels per repository is not scalable, and ensures that this tasks will need to be repeated. @phet-steele, you might consider making an official request to GitHub for a way to define labels that can be applied to all repos that are owned by an Organization.

ariel-phet commented 8 years ago

@pixelzoom I will make that request. I think it may also be possible for us to write a tool to do this ourselves through the github API, it is something I might have @mattpen look into. But I want to get a standard set of labels rolling and settled on as well, so we will do the manual step for the moment.

pixelzoom commented 8 years ago

Other PhET-standard labels:

code-review deferred phet-io-meeting performance licensing

... and scenery has a lot of labels that may or may not be specific to that repo. See https://github.com/phetsims/scenery/labels

pixelzoom commented 8 years ago

How about adding something to the phet-info repo (github_labels.md?) that lists the labels defined by PhET and their associated colors. That would save me a bit of time and guesswork, the next I need to (for example) add a "code-review" label.

ariel-phet commented 8 years ago

@pixelzoom great suggestion

@phet-steele please choose one repo to do this "fresh" on. I think expression-exchange would be good since it is a new repo. And then reassign the issue to me, so that we can discuss colors and such as a team, then once we have the full list of labels and colors, I will create a reference doc.

phet-steele commented 8 years ago

@ariel-phet Will do.

ariel-phet commented 8 years ago

Feature request sent to Github.

ariel-phet commented 8 years ago

reply from github

Hi Ariel,

Thanks for the very kind words, and for taking the time to submit feedback.

Yeah, I agree it would be useful if there was a way to have organization-wide labels as you described. Adding that is on our feature request list, but it probably won't happen in the near future.

For now, you could use the API to automatically create labels in repositories:

https://developer.github.com/v3/

Even better, if you pair that up with using organization-level webhooks, you could automatically create labels for any new repository created in your organization:

https://developer.github.com/webhooks/

Hope this helps and thanks again!

ariel-phet commented 8 years ago

I think I will make an issue in chipper to investigate the above

ariel-phet commented 8 years ago

Issue created here https://github.com/phetsims/chipper/issues/425

phet-steele commented 8 years ago

@ariel-phet the website repo also has a lot of labels that seem pretty specific to it. So I'm thinking three options: Should they not be put on the list and then deleted when the standard list is incorporated? Should they not be put on the list and then not deleted when the standard list is incorporated? Should they be put on the list and therefore be in every repo?

This question really applies to every repo with arguably repo-specific lables.

ariel-phet commented 8 years ago

@phet-steele if custom labels already exist (such for the website repo), the standard list should merely augment this list, we should not add these to the standard list.

samreid commented 8 years ago

Everything above looks good so far. There is another label I often use, let me describe how it works and we can decide together how to name it and if we want to standardize it in our labels.

Let's say I'm working on Moving Man and the sim team + QA team have identified 4 issues that require work. I fix the first issue, but I don't want to close it until it has been verified by the person that reported it. I don't want to reassign it to the person that reported it until a new dev version has been posted. And I (often) don't want to publish a new dev version until I have addressed the 3 other issues as well.

How have other developers coped with the preceding situation? Would a label help?

jonathanolson commented 8 years ago

@samreid, I had a "fixed-pending-testing" label for molecule-shapes for this exact reason. https://github.com/phetsims/molecule-shapes/labels/fixed-pending-testing.

@ariel-phet, list of issues looks perfect.

Setting a script up that uses the GitHub API sounds like the best path.

samreid commented 8 years ago

@jonathanolson I think I used ready-for-testing, but I like fixed-pending-testing as a standardized-cross-repo label.

UPDATE: I added fixed-pending-testing to the list above.

ariel-phet commented 8 years ago

@phet-steele I believe you also had some thoughts...was "multitouch" one of them?

phet-steele commented 8 years ago

@ariel-phet yea, it's already on my list

ariel-phet commented 8 years ago

@phet-steele cool, please add any on your list to the comment above

phet-steele commented 8 years ago

Here's the list so far. The first seven are the default ones (they can always be deleted though). Should summer-2015-redeploy be added?

bug duplicate enhancement help-wanted invalid question wontfix

master-checklist top-priority high-priority medium-priority low-priority wishlist requires-kathy developer-meeting phet-io phet-io-meeting teaching-resources a11y design design-meeting code-review deferred performance licensing multi-touch QA misc i18n artwork fixed-pending-testing status-meeting

Last edit: 1/20 9:46 am

ariel-phet commented 8 years ago

hey @phet-steele I made a few edits

removed "developer" "graphic-arts" (these are very tasks repo specific) and changed "quality assurance to "QA" (faster to type)

summer-2015-redeploy does not need to be added

pixelzoom commented 8 years ago

Here's how I handle what @samreid described in https://github.com/phetsims/tasks/issues/465#issuecomment-170078050...

I don't use labels to address this, and I close issues as I address them. I track issues that need to be verified by associating them with their RC task. When an issue is created related to an RC test task, I put "Related to RC test phetsims/tasks#XX" as a comment in the issue (where XX is the issue number in the tasks repo). That ensures that the issue will appear in the RC task. When the RC test is done, I review the list of issues in the RC tasks, and provide instructions on which ones need to be verified.

For example, in "RC test: Graphing Lines 1.1.0-rc.1" (https://github.com/phetsims/tasks/issues/374), you can see the issues that were created for that RC test:

screenshot_118

For the next RC test ("RC test: Graphing Lines 1.1.0-rc.2", https://github.com/phetsims/tasks/issues/445), I reviewed those issues, decided which ones required verification, then provided the following QA instructions:

screenshot_119

pixelzoom commented 8 years ago

@ariel-phet Something that would streamline the process described in https://github.com/phetsims/tasks/issues/465#issuecomment-170091387 is if the testers would handle tagging issues with their associated RC task. When they create an issue related to an RC task, put something like "Related to RC test phetsims/tasks#XX" in the comments for the issue. Not a big deal if they don't do this, and perhaps only relevant if other developers think it's useful. But it's how I keep track of what needs to be verified.

jessegreenberg commented 8 years ago

I prefer to keep issues open until after they have been verified as fixed through further testing. A standard label like fixed-pending-testing would help identify the status of these issues.

Referencing the RC task in the issue is also helpful for documenting and identifying changes and fixes resulting from RC testing.

I think both label and reference are helpful in documenting issue status.

jessegreenberg commented 8 years ago

I would prefer a11y instead of accessibility. a11y is shorter to type, matches conventions of the accessibility community, and is in sync with our code documentation style.

I also prefer i18n instead of translation for similar reasons. Changing the list, but if others disagree, they can be changed back.

samreid commented 8 years ago

I prefer to keep issues open until after they have been verified as fixed through further testing.

Yes, that's how I feel as well. I like the symmetry of having the same person that opened the issue be the one to close it.

samreid commented 8 years ago

Are any of these redundant?

when-time-allows deferred low-priority wishlist

I'm not sure of everyone's connotations attached to these phrases, or if these combinations would ever be used in combination.

ariel-phet commented 8 years ago

@samreid I suppose "when-time-allows" could be nixed in favor of simply "low-priority"

"wishlist" is truly that for me - items we have thought of that would be nice one day, but we know there is no priority for

"deferred" seems like - he we should do this, but we need to punt for the moment due to other constraints.

I will go ahead and remove "when-time-allows" from the list above from @phet-steele

samreid commented 8 years ago

@ariel-phet thanks for clarifying.

phet-steele commented 8 years ago

added top priority

pixelzoom commented 8 years ago

Surely you mean top-priority :)

phet-steele commented 8 years ago

haha yes, that's how I added it in the list above.

phet-steele commented 8 years ago

@ariel-phet I added all these to expression exchange so I could mess with the colors, check it out! Tell me if you change any colors, I'm keeping track of hex codes.

ariel-phet commented 8 years ago

@phet-steele thanks...I think we will discuss at dev meeting

ariel-phet commented 8 years ago

@phet-steele I also realized we should have a "status-meeting" label, adding that to the list

ariel-phet commented 8 years ago

Began a table to document (which we can eventually use for a json file) here https://github.com/phetsims/phet-info/blob/e107784c98c62781bacb8905391f5f3eb17e6ce0/issue-info/labels.md

mattpen commented 8 years ago

As soon as this table is complete, I can write a script to standardize all the repos. It's currently missing the hex-codes for the colors.

pixelzoom commented 8 years ago

I've seen several references (such as http://programmers.stackexchange.com/questions/129714/how-to-manage-github-issues-for-priority-etc) that recommend organizing labels into "groups", as a way to add some structure to GitHub's free-for-all label feature. Labels are grouped by using the general form <label-group>:<label-name>. Labels within a group are mutually exclusive (i.e., you shouldn't have an issue that has 2 labels from the same group.)

For example:

"type" group: • type:bug • type:enhancement • type:question • type:task

"priority" group: • priority:low • priority:medium • priority:high • priority:deferred

"status" group (to describe where an issue is in the workflow): • status:in-progress • status:awaiting-verification (not sure which others would be appropriate for PhET's workflow)

This makes a lot of sense to me, but might be more complexity than PhET wants.

ariel-phet commented 8 years ago

And don't forget the "meeting" group: :smiling_imp:

ariel-phet commented 8 years ago

I am liking @pixelzoom suggestion in https://github.com/phetsims/tasks/issues/465#issuecomment-178176176 I am going to play with this in expression exchange as I work on the color scheme

ariel-phet commented 8 years ago

example of colors and proposed labels here using groups https://github.com/phetsims/expression-exchange/labels?sort=name-asc

samreid commented 8 years ago

This label may be a typo "multitouch0000FF" ?

ariel-phet commented 8 years ago

How apropos that the multitouch label got fat fingered...fixed, thanks @samreid

samreid commented 8 years ago

The alphabetical grouping is an unexpectedly nice feature here, I like it.

ariel-phet commented 8 years ago

One break I decided to try from the general scheme was priority1, priority2, etc for that group name. I found when scanning the labels when creating an issue it was nice to have these in a clear hierarchy.

ariel-phet commented 8 years ago

and I agree @samreid - the alphabetical grouping seems very efficient for this large set of labels and seem good for scalability - thanks for the suggestion @pixelzoom !

mattpen commented 8 years ago

I think these look great. This will really help with workflow. Are the labels in this repo finalized? I can just use this as the model instead of the table above. I can propagate the labels throughout the rest of the organization whenever they are ready.

samreid commented 8 years ago

I can propagate the labels throughout the rest of the organization whenever they are ready.

Is there a migration path, so that things currently marked with "high-priority" would get mapped to the new name? I've been out of the loop on this conversation.

ariel-phet commented 8 years ago

@mattpen lets wait until we discuss a bit more at developer meeting. Once everything is settled I want to actually document it in the phet-info file as well as couple of examples of useful searches with labels.

mattpen commented 8 years ago

Is there a migration path, so that things currently marked with "high-priority" would get mapped to the new name? I've been out of the loop on this conversation.

My 2¢. Backwards compatibility with the existing labels would make automating this project significantly more complex. For example, it would be difficult to know if a repo is using "high-priority" vs "high priority" (no hyphen) as any user can define a new label. The website repo I know has at least one misspelled label -- "HMTL5 Sim Translation". This would involve a lot of manual checking.