Mark Smith (marksmith) wrote in lj_dev,
Mark Smith

Zilla Etiquette

It has been brought to my attention that since there are no real documentations on development, sometimes certain boundaries are overstepped and then people don't know what's going on and other people get upset and etc etc etc.

This is a rough draft on a "Zilla Etiquette" document that I'd like some feedback on. So yeah, comment and I will revise.

Opening a New Bug
Before you open a new bug, please do a search to find out if the bug you are opening exists. Look for things that are similar or identical to yours. Duplicating bugs just takes your time to open it and other people's time to close it. Some bugs are really hard to find, though, so if you don't find it after spending a little time searching, go ahead and open it. Someone will mark it as a duplicate if it is one.

When you open a bug, you will want to make sure that you provide enough detail for others to reproduce it. If you're opening a request for a new feature, please remember that suggestions for features go to suggestions. (In most cases--support/abuse/dev has other paths of opening feature requests, but in general, it's always after there's been open discussion. You on your own opening a feature request is not a good idea, in general.)

Marking as a Duplicate
If you've found a bug that is a duplicate of another bug, in general you can mark it as a duplicate if you have privs. Basically, a duplicate is defined as a bug that is almost identical to another bug. Usually the best bet is to close the less active bug in favor of the more active one--even if the more active one is newer.

Closing a Bug
A bug should be closed under very few circumstances:

- It has been patched and committed to CVS. An employee will do this.
- It has been resolved by another commit that happened to fix this. Comment to the bug with the URL to the changelog entry that fixes the problem, please. Anybody can do this.
- It is a duplicate. See Marking as a Duplicate.
- It is determined that this won't be fixed. Employees generally do this.
- It can't be reproduced and is closed as invalid. Also usually employee turf.
- It's junk. If it's an empty bug, or someone writing their journal entry, go ahead and close it. Don't care who does this.
- New scope. This sometimes happens when a bug is opened, then some discussion happens and it is decided that the bug is no longer valid, but something ELSE should happen. In general, it is best to close the first bug, open a new bug, and copy over the CC list. That way the two issues are maintained separately.

I can't think of any other reasons for a bug to be closed. We generally don't use the other options Zilla provides for closing status.

Posting a Patch
If you've written a patch that will fix a problem, great! You can attach it quite easily using the Create an Attachment link that Zilla provides. Writing a patch isn't in the scope of this document, but we welcome anybody who wants to help out. Don't be afraid to jump in and attach a patch to a bug. But please, make sure to test it first. If you don't have the ability to test your patches, you may want to consider holding off on development until you can or finding someone to test them for you before you attach them to bugs.

Please test your patches before you attach them. It's especially annoying, from a tester's point of view, to download a patch, apply it, then test it, to find that the page won't load due to some syntactical errors. This happens to all of us at one point or another, and I've done it a bunch of times too, but try to be careful. :)

And by test, I mean apply your code and check for the desired functionality. You will want to test all scenarios--logged in, logged out, authenticating as another user, communities, shared journals, syndicated accounts, users, deleted users, purged users, suspended users, et cetera. Just test your code and make sure it doesn't interfere with other parts of the system.

CCing People on a Bug
Adding yourself to the CC list is fine. Adding others that you think should see the bug to the CC list is fine. Adding every LJ employee in hopes that one of them will do it... that's generally a bad idea unless it's a very important bug.

If you feel so inclined, check out for a list of people that would like to be CCd on various types of bugs. Some people like to be on all bugs, some people like to be on UI related bugs, et cetera.

Assigning a Bug
Employees tend to float around from project to project. Some employees don't mind being assigned bugs, some do. You will want to talk to the person you are thinking of sending the bug to in order to find out what they think. Don't assign to an employee out of the blue, that's the fastest way to get your bug overlooked. Usually we already have a list of projects a mile long, and adding more just isn't much fun.

The only exception is a high priority bug (see Bug Priorities below). But you probably shouldn't be opening a bug for it in the first place unless you know how the security system works. In general, a security/exploit is easy to fix and caused by a code oversight, so other methods of notification should be used.

Commenting on a Bug
Everybody likes to get their two cents in, and that's fine. But please keep comments to be related to the bug in at least some capacity. Arguments and conversations are almost never a good idea. That field is for comments, not arguing for or against implementation of something.

A bug should never grow past 20 comments. Hitting 50 is a sign that either the patch is too big (covers too much ground) or policy hasn't been defined clearly enough to make a patch in the first place. Policy discussions should happen on LiveJournal in a community. Discussions on the best way to implement a patch are okay if they don't get out of hand.

For very long discussions, lj_biz is the best place for policy discussions the affect users. Should we hide community memberships? Should we hide friend ofs on banning? Those sorts of questions go there. On the other hand, if you are asking for feedback on the best way to code something--use lj_dev.

Usually commenting to tell someone they did something wrong is a bad idea, as well. Click on their name and email them. Don't publicly make derogatory comments. Oh, and Zilla policy isn't discussed in bugs. If you have Zilla usage suggestions, use lj_dev.

Reopening a Bug
This one is difficult. It is okay to reopen a bug if it has been closed very recently (past day or so) and it wasn't resolved according to how it was marked. For example, if a bug is open, someone writes a patch, and that patch gets committed, the bug is usually closed. Then, if you discover that there was a problem with the patch, you should reopen the bug and comment that there's a problem with the fix.

If it's been a few weeks and there is an issue with the feature, a new bug should probably be opened. For example, FOAF support is rolled out, and three weeks from now someone notices that the FOAF-knows friends group doesn't work right... that should be opened as a completely new bug and the person who fixed the original bug should be added to the CC list.

Some very old bugs were closed as WONTFIX because, at the time, it was impossible to do whatever was being asked. These bugs can sometimes be reopened by an employee. If you think one of these bugs should be reopened, go ahead and contact an employee and let one of us take a look at it.

Getting Zilla Privileges
My general policy is that developers get privileges. People who write patches. Usually I give out privileges after your first patch (when you email me and ask; marksmith/at/ Employees get privileges for being employees. Other people on a case by case basis--talk to me if you think you need 'em.

Privileges give you the ability to modify bugs that aren't yours. Closing them, reassigning them, adding and removing keywords, et cetera.

Bug Priorities
This is a big issue. There are some types of bugs that are very high priority and should be dealt with in a different way. For example, if you're cruising the site and you notice that something is broken in such a way that non-public user posts are being shown to the public, this is a drop everything and tell someone problem.

In general, feature requests are lower priority than problems with the system. Any bug that leaks non-public information (especially entries) is something that should be brought to the attention of an employee fairly quickly. Something that makes a feature unavailable is a higher priority than something that is just annoying.

The default priority is P4. Unless you have discussed it with a more experienced volunteer developer or an employee, please do not change this priority. While priority is not always used to determine which bugs get fixed, it is used enough in views that it is annoying to see "fix my marquee tag" as a P1 bug. :)

Bug Keywords
There are a few main keywords: patch, needs-review, reviewed. When someone posts a patch to a bug, feel free to add the patch keyword. When you've determined that the patch is good in your own estimation (you've reviewed the patch and tested it yourself), you can mark it with the need-review keyword. Someone else (it has to be someone other than the person who wrote the patch) can then come along and look at the patch. After they've also tested it, they can remove the need-review keyword and add in the reviewed keyword. If the reviewer finds a problem with the patch, they should remove the need-review keyword and add in a needs-improvement keyword.

Employees sometimes go looking for bugs with the keywords of "patch, reviewed" and will see about getting them committed to CVS. It's not a guarantee to get your bug looked at, but it's a lot better than letting it languish without any keywords.

Not everybody uses the keywords. Most people forgot. That's something that I'd like to see changed--they are there for a reason, and they do serve a purpose if we all use them.

Determining Bug Ownership
In general, bugs are owned by one person who has decided to "take ownership" of an issue and see it through. For the most part, whoever the bug is assigned to owns it. We haven't placed much emphasis on the NEW/ASSIGNED statuses, so those usually aren't good indications of a bug's status.

If you come across a bug, you should use the following criteria to determine who owns it. First, is the "assigned to" person active in the bug? (Are they commenting, reviewing patches, writing patches, or something?) If so, then they own it. Else, is someone else actively patching the bug? The lead in the patching effort should be considered to own the bug.

If you come across a bug that is inactive and sitting there for more than a month and you would like to work on it, you should ask the current "assigned to" person for permission to reassign the bug to yourself. They may tell you to never ask them again and feel free to take any bugs you want, but in general, it's best to ask. Also, you may want to CC the person you remove from the assignment list, just in case they would like to keep up with that. Again, they will tell you if they don't want to be CCd when you ask about stealing the bug.

  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded