• Best Practices
  • Rule: Always put a JIRA issue reference in commit messages
  • Rule: Don't create unnecessary issues
  • Rule: Don't reopen issues closed for a released version
  • Rule: Use nice user-friendly titles
  • Rule: Don't set a "Fix Version" field for some issues
  • Rule: Set all the versions in "Fix Version/s"
  • Rule: Use the appropriate resolution type
  • Rule: Close issues that XWiki committers don't plan to implement
  • Rule: Assign contributor when there's a Pull Request
  • Rule: create lowercase labels and without versions
  • Rule: Always set an assignee when closing an issue
  • Rule: Choose the right issue type
  • Rule: Regression Handling
  • Rule: Use the right labels
  • Rule: Non-code issues are allowed
  • Rule: Components must be specified
• Creating a JIRA project
• Retiring a JIRA project

Best Practices

Here are some rules on how to use JIRA for XWiki projects.

Rule: Always put a JIRA issue reference in commit messages

The rationale behind this:

• One consistent way to manage all the work to be done on the XWiki project. It also means there's no unaccounted work, meaning anyone can go to JIRA and query it and see what everyone has been working on.
• Automated release notes/change logs. When we release a version we can simply do a JIRA extract and it'll give the full change log of what happened. This is really important for our users to see what has been done when in XWiki.
• Traceability. When you use the JIRA issue number in your commit, the JIRA DVCS Connector Plugin can show the modified files directly from JIRA. This is quite useful later on, when someone is looking at a JIRA issue and wants to see what was modified. In addition Fisheye is also integrated with JIRA and when you browse the source repository you can see the JIRA issue associated with files.

Of course this shouldn't be done for any trivial things like adding a small javadoc, renaming a single variable, cosmetic changes, ignore files, etc.

JIRA issues can be marked "confidential", e.g. to hide the details of a security issue until it is fixed. Such issues should also be referenced in the commit message. However, avoid exposing the details of the issue in the commit message (some time will pass until the code is released) by choosing a more neutral description.

The general strategy goes like this:

• When you plan to work on something, create a JIRA issue and assign it to yourself or simply assign an existing JIRA issue to yourself if one already exists
• Implement it
• Commit it with the JIRA issue number in the commit message. The format we follow is:

  <JIRA ID, e.g. XWIKI-1000>: <JIRA issue description>
  * <details>
  ...
  * <details>

• Close the JIRA issue

• Another acceptable variation is:
  • Implement something
  • When you want to commit it you realize you don't have any JIRA issue to put in the commit message so don't commit.
  • Create the JIRA issue
  • Commit with the JIRA number in the commit message

Rule: Don't create unnecessary issues

• If you want to know whether you should create a JIRA issue or not, ask yourself the question: "is my change going to affect any user or any extension developer in any way"? If the answer is yes then you must create a JIRA issue
• If you're fixing something related to the development of XWiki (but not necessarily related to code) or some code refactoring that doesn't impact users of XWiki directly then it's not mandatory to create an issue. However if you do, make sure you use the special component usually labeled "Development Issues only" in our JIRA projects. We're excluding issues in this category from our release notes.See below for more details for non-coding issues.
• Note that if you're upgrading a third-party dependency used by XWiki at runtime then you must create a JIRA issue using the special component usually labeled "Dependency Upgrades" and this needs to make it in the Release notes since it impacts XWiki users. If you're upgrading a third-party dependency only used at build time (for example the Selenium dependency) then you should use the "Development Issues only" component.
• If you're fixing or reporting an issue related to code that's been introduced in the current version being developed, you shouldn't create a JIRA issue. Actually, if you did, you'd be hard-pressed to find the correct "Affects version" to use! . Instead, use (or reopen) the existing JIRA that affects the current version being developed. If you're fixing it yourself, just use the same issue key. If you're reporting a problem, just reopen the issue and add a comment for the developer to see and fix before releasing.
• If you're adding some translations on l10n.xwiki.org it's not necessary to create an issue in the l10n Project's JIRA. It would cause too much overhead and it shouldn't appear in the Release Notes. Thus, if you create a JIRA issue, make sure to use the Development Issue Only component for translation issues (i.e. for issues about the translation. If the issue is about translation key then it's different and it should appear in the Release Notes).

Rule: Don't reopen issues closed for a released version

If you spot an incorrectly or incompletely fixed issue that was closed but the version it was closed for is already released (i.e. no more development can be done for that version), then you must never reopen such an issue. Instead, you should create a new issue that describes the work left to be done or the fact that the problem still exists after the attempted fix and link the new issue to the old one.

The main reason is that a fix for an issue must never span commits across multiple versions and we need to be able to clearly indicate what is the version where the issue was fixed in.

The only case where reopening such an issue is allowed is when the closed issue has no commits associated to it (i.e. closed as Won't Fix, Duplicate, etc.).

Rule: Use nice user-friendly titles

When you create a JIRA issue always take the time to put a nice title for the issue. The title must be understandable by a user so don't describe the issue technically but rather in what way it affects users. For example don't say "Fix the addXXX API to return an Array List" but rather "Allow creating several pages at once".

Rule: Don't set a "Fix Version" field for some issues

Issues that are closed with "Won't fix", "Duplicate", "Cannot reproduce", or "Incomplete" must have a "Fix Version" field set to "None" so that they don't appear in the Release Notes, as JIRA doesn't make the distinction visible and this causes confusion.

Note that “Solved by” issues must have a “Fix Version” set so that users can easily query JIRA to find in which version an issue has been fixed (rather than have to look in linked issues). This is useful for example for security issues which are closed as “Solved by” when they are fixed by other non-security issues. It’s also simpler for users to understand what’s been fixed in a given release, since the “Solved by” issue is usually described from a user perspective while the fixing issue is often more technical and more indirectly related.

Rule: Set all the versions in "Fix Version/s"

When closing a Solved or Fixed jira issue, the next version of each branch where the issue was applied should be added to "Fix Version/s". For example if you commit an issue in master, and stable-17.4.x with the respective next versions being 17.5.0-rc-1 and 17.4.1, you should indicate both versions.

Rule: Use the appropriate resolution type

The description of the different resolution types can be found directly in JIRA help.

Rule: Close issues that XWiki committers don't plan to implement

• We close issues that we know we won't fix (using a "Fix For" value of "Duplicate", "Incomplete", "Cannot Reproduce" or "Won't Fix"). We might not want to fix them for several reasons but one reason is that the issue is for an old XWiki project version.
  • This is especially true since XWiki committers are only officially supporting a few branches. Of course, any committer wanting to
    fix any old issue is free to do it.
• Leaving these issues open is not a good idea since:
  • It sends the wrong signals that we're going to fix the issue
  • The issue can still be found with a search even if closed
  • When we close it then the reporter can explain why it's so important for him/her, or not. Which we wouldn't know if we hadn't closed it
  • Contributors can reopen issues and attach a patch or just create a new issue
  • It means that for all other issues we plan to fix them at some point

Rule: Assign contributor when there's a Pull Request

• If a contributor opens a PR, assign the corresponding JIRA issue to the contributor
• If the contributor doesn't have a JIRA account then ask the contributor to create an account to assign him/her and in the mean time assign the committer merging the PR (so that if no account is ever created the committer stays assigned)
• If you have to make substantial modifications to the PR, then you decide who gets assigneed (contributor or you), on a case by case basis.

Rule: create lowercase labels and without versions

The idea is consistency:

• We use lowercase labels
• Don't put specific versions in labels, instead use the Environment field to add more details about versions.
  • For example don't create a tomcat9 label, instead use the tomcat one and put "Tomcat 9.x" in the Environment field.

Rule: Always set an assignee when closing an issue

All closed issues must have an assignee set (even if the issue is closed as "won't fix", "duplicate", "invalid", etc). The assignee represents the person who's taken the call and became responsible for the issue closing.

Rule: Choose the right issue type

The definition of issue types are:

• Bug: A problem which impairs or prevents the functions of the product.
• Idea: An idea or wish (something not sure that'll happen but that would be cool)
• Improvement: An improvement or enhancement to an existing feature or task.
• New feature: A new feature of the product, which has yet to be developed.
• Task: A task that needs to be done.

All other types must not be used.

Notes:

• Subtask: Must not be used. We need to remove it but it's hard to do now as lots of issues were created a subtasks in the past and we need to clean that up before we can remove this issue type.

Rule: Regression Handling

Regressions must be indicated in JIRA issues as follows:

• The regression label must be set
• The "Priority" field must be set to Blocker if the regression was first introduced less than two years ago, otherwise it should be set to Critical.
• The "Fix Version" field must be set with target versions being the next versions for the supported branches
• A developer must be assigned ASAP to the issue.

Rule: Use the right labels

Use the following labels:

• Usability labels
• Security label
• Regression label
• XWiki Days labels (Each XWiki Day uses a different JIRA label)
• testneeded label for issues about missing tests that need to be added
  • Note: Manual QA uses this label
• responsive label for issues related to Responsive UI (especially XWiki UI on small screens, like mobile)
  • TODO: Decide what we do with mobile, ie whether we keep both labels or not
• flickering label for issues related to flickering tests
• performance label for issues related to performance (memory needs, speed of execution, scalability, etc)
• Browser-related labels: ie, chrome, firefox, etc
• Servlet-container-related labels: tomcat, jetty, etc
• Database-related labels: mysql, mariadb, postgresql, oracle, etc
• OS-related labels: windows, mac, etc
• (Deprecated) configurationtesting label was used for issues related to Environment test (docker-based tests)
• nestedspaces label for issues related to Nested Spaces or Nested Pages
• onboarding label for simple issues that can be tackled by developers doing onboarding on the XWiki project
• l10n label for issues related to Localization. Note: Also set this label on issues using the "Localization" component

See also the use of lowercase labels.

Rule: Non-code issues are allowed

Also see the Don't create unnecessary issues rule.

We allow creating JIRA issues related to the development of a given version of the XWiki product but that don't result in code commits. This allows to materialize all the issues that need to be fixed for a given release (i.e. it allows to define the roadmap fully in JIRA).

Examples:

• UI Design issues (resulting in design proposals on design.xwiki.org and the forum).
• Asking the community about something to decide of how to implement something.
• Investigate some library or software that could be useful prior to deciding to use it.
• etc

The rules are:

• Use the Development Issue Only component and a Task issue type.
• Use the "fix version" corresponding to the timeframe in which the issue needs to be fixed (ie the version of XWiki before which it needs to be fixed).
• For "affects version" you can use the latest released version or the LTS version, as you wish.
• See also the Labels rule above for any additional label that can be used.

Special rules for UI Design issues:

• The condition to close these issues is that a proposal has been made on the forum and an up to date design page on design.xwiki.org exists.
• When closing, the “documentation” field must point to an updated design page on design.xwiki.org (updated from the results of the forum discussion).

Rule: Components must be specified

Anyone closing an issue must make sure that the JIRA Components fields is filled appropriately as this allows to perform interesting queries afterwards (List of empty components to fix).

The rules are:

• Check the list of committed files (available in the right panel of any JIRA issue, under "Development"), and what Maven module they affect. This will give you the name of the JIRA Component for the change.
  • Example 1: xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-resources/src/main/resources/flamingo/less/action-menus.less -> Flamingo Skin Component
  • Example 2: xwiki-platform-core/xwiki-platform-web/xwiki-platform-web-war/src/main/webapp/resources/js/xwiki/table/livetable.js -> Web - Templates & Resources Component
• Set as many Components as there are changes from different Maven modules

Creating a JIRA project

To create a new JIRA project on https://jira.xwiki.org, follow the Contrib JIRA project creation process.

Retiring a JIRA project

Eventually, some XWiki projects will reach their end-of-life. This is often a good thing as new approaches or technologies have developed which reduce the need for the project. When a project retires, it is best to clean up loose ends to make sure outstanding users still have access to the code and the valuable project history is captured for future researchers.

Retiring steps:

• Make the project 'Read-Only' by using the "XWiki Retired Project Scheme" permission scheme.
• Change the name of the project by prepending it with the {RETIRED} label (e.g. Forum Application -> {RETIRED} Forum Application).
• Move the project to the "XWiki Retired Projects" category. Edit the project and set its new category.
• Update the project's description accordingly, informing the users that the project is no longer active.
• If there are open issues that are still valid (i.e. they still need to be implemented), consider moving them to a new active JIRA project.