Reporting an Issue

[resplin]

• Reporting an Issue in Alfresco Community Edition
• Inactive Accounts
• No Support Requests
• Submitting an Issue
• Guidelines on a Good Issue Report
• Bug Report Template
• Improvement Request Template
• Contributions
• Documentation Issues
• Security Issues
• Automated Reports from Security Scans
• Issue Triage Process

Reporting an Issue in Alfresco Community Edition

Alfresco maintains a public issue tracker at

http://issues.alfresco.com

Anyone can sign up for an account.

We struggle to manage the flow of incoming issues, and need your help to keep the issue tracker a useful platform for collaboration. Please recognize that we commonly close bug reports because the observed behavior is as designed, even though that design isn't optimal or does not match the use case of the reporter. We also commonly close bug reports which we acknowledge are valid issues simply because we don't think we will be able to work on them in the reasonable future. Both of these scenarios are unfortunate, but we have to prioritize our efforts.

In 2016, we closed a significant percentage of issues due to them being unclear, duplicates, non-reproducible, or not a current priority for us. However, we were able to resolve as "Fixed" or "Done" more than 10% of the issues submitted that year.

Inactive Accounts

In order to manage the license cost of our issue tracker, we disable accounts that have not been used for two years. If your account has been disabled, please email community@alfresco.com and we will re-enable it for you.

No Support Requests

The issue tracker is not the right place for support requests. It distracts the engineering team from working on actual issues and improving the product.

Requests for help should be made in this social community. Please help others as often as you request assistance. If you are not getting volunteers willing to help you out, you should review the list of https://community.alfresco.com/community/about-this-community/blog/2016/09/07/things-you-should-incl... You can also look to hire some help in one of the following ways:

• Subscribing to Alfresco Support,
• Posting an "Opportunity Announcement" in the area to Connect‌.
• Reaching out to someone recommended by the Order of the Bee.
• Reaching out to members of this community who have shown themselves to be helpful and whose profile includes professional contact information. Make sure they know you are offering to hire them, or they may misunderstand your request.

Submitting an Issue

Each Alfresco open source project maintains its own processes. You can learn about those processes in the Project Overview: Content Services‌ section of this community.

In general, community contributed reports of issues in Alfresco Community Edition should go into the ALF project at the Alfresco issue tracker. These issues go through our Issue Triage Process‌. Members of the community can only create issues in this project, but can comment on public issues in most other public projects. Issues are created in MNT based on support requests, and so default to being private. We open them when we validate that there is no customer information.

Though Alfresco's open source code is generally hosted on GitHub, the projects that make up Alfresco Content Services do not use GitHub for tracking issues. By directing all issues into the ALF project of the Alfresco issue tracker, we receive the following benefits:

• It is easier for reporters to know where to report an issue.
• We have a consistent process.
• We can accept contributions in a variety of formats.
• We can ensure the acceptance of the Alfresco Contribution Agreement‌ for all contributions to our project.

Other open source projects sponsored by Alfresco Software, such as Activiti, Aikau, and the mobile apps, have their own projects in JIRA or use GitHub as their issue tracker. To raise issues against those projects, you should refer to their project information in this community.

Guidelines on a Good Issue Report

• Please search the issue tracker before creating a new issue! If you find it is already reported, add a comment and any additional environment or version information that might help us with the issue.
• Please follow the appropriate template below. If we cannot understand or reproduce your issue, we will have to close it.
• Don't include personal information, as the issue will be public.
• The best issue reports link to a pull request in the Git code repository.

Bug Report Template

A bug is an observed behavior that does not match the expected behavior for the system. If we cannot reproduce the bug, then we will have to close the issue. Therefore, it is important that we have the necessary information in the format that we expect.

The best reports follow these guidelines:

• Summary: A short sentence briefly describing the problem.
• If the bug affects the security of the product, select the relevant Security Severity and read the section below.
• Priority: This will help us understand how you feel about the issue, but we are likely to change it to match our criteria after we do further analysis.
• In the Components field, select the areas of the product that are affected by the issue so that the right team gets notified.
• In the Description field include:
  
  • Description: Provide a summary of the issue
  • Steps to reproduce:
    
    • Detailed steps that reproduce 100% of the time, or description of what has been attempted to reproduce.
    • Write as if the person reading the report does not know Alfresco very well.
    • Prefer <ol> ordered list to <ul> unordered lists (bullets) as one can refer easily to a given step.
    • Prefer to call test users 'userX' instead of 'test', test folders 'folderY', instead of 'a12', test documents 'testZ.txt', instead of 'y123', that makes the Jira more readable.
  • Expected Behaviour: What should happen and why
  • Observed Behaviour: What is actually happening
  • Analysis to date:
    
    • Business impact / priority / urgency
    • Is this a regression? In which version did the behavior last work as expected?
    • Any notes on your analysis that we should know about, such as a work-around or proposed solution
• If you include code to fix the issue, make sure to add the PatchAttached label so that it goes to the top of our queue.
• At can be helpful to include Attachments such as log files and relevant configuration files.
• In the Environment field, add in all the relevant environment information such as operating system, browser, database, and Alfresco installation method.
• In the Affects Version/s field, mark every version of Alfresco where you have observed the problem.

Improvement Request Template

The ALF project has an issue type 'Improvement Request'. This is used for requesting an enhancement to the system that includes new functionality and is not a fix to existing intended behavior. Unless an enhancement request is for a part of the product that is already on our roadmap, or is otherwise requested by our paying customers, we are unlikely to prioritize these issues. The best way to request a product enhancement is to purchase a support subscription and raise the enhancement request through support.

If you decide to create an 'Improvement Request', make sure to follow the guidelines for reporting bugs, but in the Description field use this template:

• Summary of the enhancement
• Steps showing the current behavior
• The desired behavior
• The business case for making the enhancement (i.e. how will it increase sales)
• Any workarounds in the current product

Even if your enhancement request is closed, it will be viewed by Alfresco Product Management and considered against future roadmap priorities. The workarounds section of the enhancement request are often useful to other people with similar needs.

If you intend to contribute an enhancement, you should refer to the section on "Contributions".

Contributions

If you are making a contribution to an Alfresco open source project which you want us to evaluate, please follow the steps to Submitting Contributions‌.

If you are a customer or partner who wants to make a contribution to one of Alfresco's proprietary products, you should contact Alfresco Support.

Documentation Issues

The best way to improve the documentation is to submit using the feedback form on the relevant page of the documentation.

Security Issues

System security is one of our highest priorities as we understand security is a requirement to our customers and partners. When reporting a security issue, we need to get enough information on the vulnerability to properly investigate, reproduce, and rate the severity of the issue before passing through to engineering for fixing.

• Before raising a new security related issue, please search the issue tracker to ensure that the vulnerability has not already been addressed.
• Please mark the issue with an appropriate security severity. Remote exploitable vulnerabilities should be marked High. This will cause the issue to be private so that we have a chance to review it and prepare a patch before public disclosure.

Automated Reports from Security Scans

An automated security report, such as from an automated penetration test or code scan, can often give generic information on a set of possible vulnerabilities. Most of these possible vulnerabilities have already been reported to us, and we have already determined that we are not in fact vulnerable. Therefore, the information that we need to be able to progress these potential exploits within our security team are as follows:

1. Ensure that the security issue 'relates' to Alfresco. This sounds obvious but often security reports just give a 'possible' exploit name based on packet matching or generic information on the environment. We need to be sure that the vulnerability being raised actually relates to a specific area of Alfresco.
2. Give details of the exploit(s) and a practical example of how to exploit it/them. We understand that this is not always possible, however if we don't fully understand the vulnerability details or ways to exploit it, then we will have to clarify that before we progress the issue. Giving us a detailed breakdown of the (potential) vulnerability as well as a practical and reproducible example of how to exploit it, will enable us to not only progress the issue to our security team much quicker but also help us in establishing whether or not the issue is already addressed in a later version. Please also list any tools used/required to perform or prove the exploit.
3. If you have a security report, we will need the specific security issues isolated, detailed and (hopefully) hand-verified in the case (as above). Additionally, it must have been run against the most recently available version of Alfresco.
4. Ensure that any relevant logging, tracing or output complementing the security issue is provided.

Issue Triage Process

The process Alfresco uses to triage issue reports is documented the page Issue Triage Process‌