Engine/Filing Engine Bugs and Feature Requests

The Engine Issue Filing Process (a.k.a. Care and Feeding of Your Engine and Engine Development Team)

N.B. Ok, yes, the “engine team” is really just Krista, so this sounds weird and pompous, but we don’t want it to be a one-woman show forever, right? So… optimism!

So you want to file a bug and/or feature request against the engine, eh? Great!

For those that have access to dev JIRA, the process is to file a ticket there as described below. If it is more or less urgent, please let Krista or Sibu know so it can be prioritised effectively.

For those that don’t, the process depends on who you are:

  • If you’re in service, you need to file an issue in your JIRA and it can be assigned to dev.

  • If you’re not:

    • if it’s a design issue, talk to Volker.
    • if it’s a weird bug, talk to service (they can track and push the bug to dev if need be).
    • if it’s really an issue you’re having with a specific app, please talk to the app’s team or Sibu. They can push the bug to the engine if it’s determined it’s not an app or adapter issue.

While Krista is happy to chat with you about problems in IRC, if it gets to the point where it’s actionable, please follow the above procedures. The engine team of one uses JIRA extensively to track issues - anything solely in IRC may be forgotten due to the lack of clones available at this time.

Engine Issues

Filing Bugs

Generally speaking, if there is something broken in the extant code, you want to file a bug. Sometimes it’s a design issue, sometimes it’s naughty code. Either way, bugs are for when things are broken. Features are for when there’s something you want the code to do that it doesn’t yet. Keeping the two distinct makes your engine monkey happy.

When you want a design change because something does not behave in the way you think is best, you must talk with Volker.

When filing bugs against the engine:

  1. Don’t file a bug unless it’s reproduceable.

  2. Provide enough information to reproduce it. This means giving as much information about the inputs, outputs, function calls (and which adapter is being used) and environment as possible. In general, original messages and necessary keys (or reconstructed new messages and keys which can be used for testing) are going to be necessary for the engine team to debug the behaviour.

  3. If 1 and 2 are not fulfilled, the engine team is very likely NOT to touch the bug. Sometimes there’s a good reason you can’t fulfill 1 and 2, though, so if there is, and the engine is the only place to diagnose the problem, discuss it with Krista including the information about why.

  4. Sending patches is usually less-than-ideal. There’s a lot of work in validation which is often not less effort than writing it from scratch. (This depends on the issue, however.) Send descriptions of how to solve it, by all means, but the engine team is usually aware of the unintended interactions between various parts of the complex engine in a way someone doing a code review to root cause something doesn’t.

  5. Please pay attention to “Assignment of priority and responsibility” below.

Filing Feature Requests

Feature requests are for new or enhanced functionality. Please provide as much information as possible; in general, larger feature requests have to go through the feature request committee first. Smaller ones (changing the way a file is saved because the current method is not ideal, etc) can be filed directly and should go through the “Assignment of priority and responsibility” process below.

Tasks

Tasks are usually assigned internally by the engine devs as a way of breaking down and tracking parts of larger issues. There is no process for this to be used externally right now.

Assignment of Priority and Responsibility

Right now, priority is assigned by either Krista, Sibu, or possibly Patrick. Volker’s choices override this, obviously.

If you’ve discussed it with Krista and she says “please file me an X prio bug”, then go ahead and assign it to her and use that priority yourself.

Otherwise, the ticket should be assigned to Sibu, and Sibu will determine the priority appropriately. If there are reasons it should be prioritised a certain way, please tell him this. While it’s totally understandable that it’s easier to go to Krista and say “I have this problem and it’s important and please fix it now”, the more context switches and tasks added to her plate, the less that gets done, and Sibu is the owner of management priorities and can match these to filed issues with this expertise in a way that the engine team cannot alone.

(This doesn’t mean that the engine team won’t yank it from the queue and start working on it if there is an engine priority that demands it or if there is a clear reason to work on it now, but please help everyone do their jobs and keep a handle on tasks by going through the right chain of reporting here. Thank you from the bottom of Krista’s cold, dark, Sithy heart :)

Required Information

This obviously depends on the situation, but in general…

  1. Original messages

    • with the keys necessary to encrypt and or decrypt
    • with original headers
    • if a private key is attached, you MUST also give me the public key

  2. Systems on which the problems are known to occur or which are the target for implemented features, if relevant

  3. When possible and relevant, the .pEp_management.db file

  4. If it is a suspected part of the problem, relevant keyrings may also be useful

  5. If original messages are not possible (e.g. due to privacy reasons), please take the time and create test mails and keys which trigger the behaviour on your own and attach them.

The quicker the engine team can reproduce your issue (e.g. the more complete the above information), the faster your problem can be solved! (Also, the more likely it is to move up the queue)

Dos and Don’ts

  1. Please don’t work around the process by sending engine team members an email or trying to get the issue taken care of solely over IRC. IRC and Krista’s memory are both ephemeral, and priorities are hard to manage in either place

  2. When an issue is marked as done, UNLESS THE ORIGINAL BUG, caused by the EXACT same circumstances, in a VERY CLOSE TIMEFRAME, has not been fixed by the patch, DO NOT REOPEN THAT BUG.

    • If the same issue REAPPEARS after the original issue has been closed, if a new release has occurred or more than a couple of weeks has passed, FILE A NEW BUG. You can mark it related to the first bug within JIRA. BUT DO NOT RESURRECT THE INITIAL BUG.
    • If you want additional features after the original bug or feature has been closed, FILE A NEW BUG OR FEATURE. Mark it related to the first bug within JIRA. DO NOT RESURRECT THE INITIAL ISSUE.
    • Only YOU can stop necro-posting. :)

  3. Every so often, you’d help tracking out greatly if you went through any open engine bugs you’ve filed and check to see if they are even still relevant. Sometimes a redesign or other bug fix will remove your issue when we weren’t even aware it impacted your original issue.

  4. DO feed your engine team after midnight. We are particularly partial to seafood and spicy things.