Leantime: Fixing Milestone Percentage Report Bug

by Lucas 49 views

Introduction

Hey guys! Are you facing issues with your Leantime reports not showing the correct milestone achievement percentage? You're not alone! This is a known issue in version 3.3.1, and we're here to break it down for you. This article will guide you through understanding the problem, reproducing it, and hopefully, finding a workaround until a fix is officially released. We'll dive deep into the details, making sure you have a clear picture of what's going on. Let’s get started and figure this out together!

Understanding the Issue

Milestone achievement tracking is crucial for project management, providing a clear view of progress and helping teams stay on schedule. Leantime, as a project management tool, aims to offer this functionality seamlessly. However, in version 3.3.1, a glitch prevents the milestone reports from accurately displaying the percentage of achievement. This means that even when tasks within a milestone are completed, the report might still show a 0% completion rate, which can be super frustrating.

The core issue lies in how Leantime calculates and displays this percentage in the reports section. The system correctly tracks the completion of individual tasks and reflects this progress in the milestone timeline. But when generating reports, the data doesn't seem to translate properly, leading to the inaccurate display. This disconnect between the actual task completion and the reported milestone progress can lead to misinterpretations of project status, potentially affecting decision-making and team coordination. Understanding this discrepancy is the first step in addressing the problem effectively. We'll explore how to reproduce this issue in your own setup and then discuss potential workarounds. Keep reading to get a clearer picture of the situation and what you can do about it.

Setting the Stage: The Self-Hosted Docker Environment

Before diving into the reproduction steps, let's quickly talk about the environment where this issue was observed: a self-hosted Docker setup. For those new to Docker, it’s a platform that allows you to run applications in isolated containers, ensuring consistency across different environments. This is a common setup for Leantime users who prefer to have more control over their hosting and data. Using Docker simplifies the deployment process, but it also introduces a layer of complexity when troubleshooting issues.

Self-hosting Leantime with Docker means that all the application's components, including the database and web server, are running within these containers on your own server. This setup is great for customization and security but requires a bit more technical know-how to manage. When encountering issues like the milestone percentage not displaying correctly, it's essential to consider the Docker environment as a potential factor. While the issue is likely within the Leantime application itself, the Docker setup could influence how logs are accessed or how configurations are managed. So, if you're running Leantime in a Docker environment, keep this in mind as we move forward. Understanding your setup is key to troubleshooting effectively, and we'll guide you through the steps to reproduce the issue regardless of your environment.

Reproducing the Issue: A Step-by-Step Guide

Okay, guys, let's get practical! If you're experiencing this issue, you probably want to confirm it's the same bug. Here’s a step-by-step guide to reproduce the milestone achievement percentage problem in Leantime version 3.3.1:

  1. Create a Milestone:
    • First, log in to your Leantime instance. Navigate to the project where you want to test this. Create a new milestone with a clear name and a relevant due date. This milestone will be the focus of our test.
  2. Create Tasks and Assign Them to the Milestone:
    • Next, create several tasks that fall under this milestone. These tasks should represent the work needed to achieve the milestone. Assign these tasks to the milestone you just created. This is crucial because the milestone's progress is calculated based on the completion of these tasks.
  3. Close Half of the Tasks:
    • Now, here’s where the magic happens (or doesn't!). Mark approximately half of the tasks as completed. This simulates partial progress on the milestone. This step is important because it sets the stage for the expected percentage of achievement.
  4. Check the Milestone Timeline:
    • Navigate to the milestone timeline view within Leantime. Here, you should see the correct percentage of achievement based on the number of tasks you've completed. For instance, if you closed half the tasks, the timeline should display around 50% completion. This confirms that Leantime internally tracks the progress correctly.
  5. Go to the Reports Section:
    • Now, go to the reports section of Leantime. This is where the issue surfaces. Generate a report that includes milestone progress. You should expect to see the same percentage of achievement as in the timeline view.
  6. Observe the Incorrect Percentage:
    • In the report, you’ll likely notice that the milestone achievement percentage remains at 0%, despite the tasks being completed and the timeline showing the correct progress. This discrepancy confirms the bug we're addressing. This is the key step in reproducing the issue and validating that you're experiencing the same problem.

By following these steps, you can reliably reproduce the issue and confirm that your Leantime instance is affected by this bug. Now that we've reproduced the problem, let's dive into potential reasons why this might be happening and what we can do about it.

Diving Deeper: Why the Discrepancy?

So, you've reproduced the issue – great! Now, let’s try to understand what might be causing this discrepancy between the milestone timeline and the reports. While we don’t have access to Leantime’s codebase to give a definitive answer, we can make some educated guesses based on common software bugs and how project management tools typically work.

One potential reason is a data aggregation issue. Leantime likely uses different methods to calculate and display the milestone percentage in the timeline versus in the reports. The timeline might be pulling real-time data directly from the task statuses, while the reports could be relying on a separate process that aggregates data periodically. If this aggregation process is faulty or not running correctly, it could explain why the reports show outdated or incorrect information. This is a common scenario in complex systems where data is processed and presented in multiple ways.

Another possibility is a bug in the reporting query. The reports section probably uses a specific database query to fetch the milestone completion data. If this query has a flaw, such as an incorrect join or filter, it might not be pulling the correct information. For instance, it might be missing completed tasks or miscalculating the percentage based on some other criteria. This kind of bug can be tricky to spot without directly examining the query and the database schema.

Caching issues could also be at play. Leantime might be caching report data to improve performance. If the cache isn't being updated when tasks are completed, the reports would show stale information. This is a common optimization technique in web applications, but it can lead to inconsistencies if not implemented carefully.

Finally, there could be a version-specific bug in Leantime 3.3.1. Software often has bugs that are introduced in specific versions and fixed in later releases. This issue might be a result of a change in the reporting logic or data handling that wasn’t thoroughly tested. Understanding these potential causes can help in troubleshooting and finding workarounds, which we'll discuss next.

Workarounds and Solutions: What Can You Do?

Okay, so we know the problem, we've reproduced it, and we've got some ideas about what might be causing it. Now, the big question: what can you do about it? While a permanent fix will likely require an update from the Leantime team, there are a few workarounds you can try in the meantime. These might not completely solve the issue, but they can help you get a more accurate view of your milestone progress.

  1. Rely on the Milestone Timeline View:
    • As we saw earlier, the milestone timeline view seems to be displaying the correct percentage of achievement. So, for a quick check on a specific milestone's progress, you can rely on this view. It's not a perfect solution, especially if you need aggregated reports, but it's a good way to get a real-time snapshot.
  2. Manually Calculate the Percentage:
    • This might sound old-school, but it’s a reliable way to get the correct number. Count the total number of tasks in a milestone and the number of completed tasks. Then, divide the completed tasks by the total tasks and multiply by 100 to get the percentage. It’s a bit of extra work, but it ensures accuracy.
  3. Check Error Logs (If Self-Hosted):
    • If you're self-hosting Leantime, you have access to the server's error logs. These logs might contain clues about what’s going wrong with the reporting process. Look for any error messages related to database queries, reporting, or data aggregation. While this requires some technical expertise, it can provide valuable insights. The user in the initial report mentioned that there were no error logs, but it's always worth checking.
  4. Consult the Leantime Community:
    • The Leantime community forum is a great place to share your experience and see if others have found a workaround. Someone might have a clever solution or a temporary fix that you can use. Plus, reporting your issue in the forum helps the Leantime team understand the scope of the problem.
  5. Consider Upgrading (If a Fix is Available):
    • Keep an eye on Leantime's release notes. If a new version is released that addresses this bug, upgrading is the best long-term solution. Make sure to back up your data before upgrading, just in case.

These workarounds should help you manage the issue until a proper fix is available. Remember, project management is all about adapting and finding solutions, and these tips should help you stay on top of your milestones.

Checking the Error Logs: A Deeper Dive

Let's talk a bit more about checking those error logs, especially if you're running a self-hosted Leantime instance. Error logs are like the black box of your application, recording any hiccups or problems that occur behind the scenes. They can provide valuable clues when things aren't working as expected, like in our case with the milestone percentage issue. The original report mentioned no error logs, but it's always worth double-checking, as logs can sometimes be overlooked or not configured correctly.

Where to Find the Logs:

In a typical Leantime setup, especially if you're using Docker, the error logs are usually located in the LEANTIMEFOLDER/storage/logs directory. The exact path might vary slightly depending on your setup, but this is the most common location. If you're using Docker, you might need to access the logs from within the container. This usually involves using the docker exec command to enter the container and then navigating to the log directory.

What to Look For:

Once you've found the logs, you'll want to look for any entries that seem related to reporting, database queries, or milestone calculations. Error messages often include keywords like “SQL,” “database,” “report,” or “milestone.” The timestamps on the log entries can also be helpful, allowing you to correlate errors with specific actions you took in Leantime, such as generating a report.

Interpreting the Logs:

Interpreting error logs can be a bit tricky if you're not a developer, but even a basic understanding can be helpful. Look for lines that indicate an error (often marked with “error,” “exception,” or “warning”). These messages might give you a hint about what’s going wrong. For example, a database error might suggest an issue with the query used to fetch milestone data. If you find something that looks suspicious, try searching the error message online – chances are, someone else has encountered the same issue and there might be a solution or explanation available.

Even if you don't find any obvious errors, the absence of logs can be informative. It might suggest that the issue isn't causing a hard error but rather a logical flaw in the calculation or data handling. This is why checking the logs is a crucial step in troubleshooting, even if it doesn't immediately lead to a solution.

Reporting the Issue to the Leantime Team

Okay, guys, we've done a lot of troubleshooting, but sometimes the best thing you can do is report the issue to the developers. Reporting bugs helps the Leantime team understand the problems users are facing and prioritize fixes. The more information you can provide, the better! Here’s how to effectively report this milestone percentage issue:

  1. Gather Information:
    • Before you report, make sure you have all the necessary details. This includes:
      • Your Leantime version (in this case, 3.3.1).
      • Your setup (self-hosted Docker).
      • The steps to reproduce the issue (the guide we discussed earlier).
      • Any workarounds you've tried.
      • Whether you've checked the error logs and what you found (or didn't find).
  2. Use the Right Channels:
    • Leantime likely has specific channels for reporting bugs. This might be a forum, a GitHub issue tracker, or a direct email address. Check the Leantime website or documentation for the correct channel.
  3. Write a Clear and Concise Report:
    • When writing your report, be clear and concise. Start by stating the issue: “Milestone achievement percentage is not displayed correctly in reports.”
    • Then, provide the steps to reproduce the issue, just like we outlined earlier. The more detailed you are, the easier it is for the developers to understand and fix the problem.
    • Include any relevant screenshots or videos. Visual aids can be incredibly helpful in illustrating the issue.
    • Mention your environment (e.g., self-hosted Docker) and any other relevant details about your setup.
    • If you’ve tried any workarounds, mention them. This shows that you've put effort into troubleshooting and can help the developers narrow down the cause.
  4. Be Patient and Follow Up:
    • Once you've submitted your report, be patient. The Leantime team might be working on other issues or need more information from you. If you don't hear back within a reasonable time, you can follow up politely.

Reporting bugs is a crucial part of the software development process. By providing clear and detailed reports, you're helping the Leantime team make the tool better for everyone. So, don't hesitate to speak up – your feedback matters!

Conclusion: Staying on Top of Milestone Progress

Okay, guys, we've covered a lot in this article! We started by understanding the issue of milestone achievement percentages not displaying correctly in Leantime reports, specifically in version 3.3.1. We walked through the steps to reproduce the problem, discussed potential causes, and explored several workarounds. We also talked about the importance of checking error logs and reporting the issue to the Leantime team.

While this bug can be frustrating, it's important to remember that software is complex, and issues like this are not uncommon. The key is to have a systematic approach to troubleshooting and to communicate effectively with the development team and the community. By using the workarounds we discussed, such as relying on the milestone timeline view or manually calculating the percentage, you can still stay on top of your project progress.

In the long run, the best solution will be a fix from the Leantime team. So, keep an eye on the release notes and consider upgrading when a new version is available. In the meantime, your feedback and bug reports are invaluable in helping the developers address this issue and improve Leantime for everyone.

Remember, project management is a journey, not a destination. There will always be challenges along the way, but by working together and sharing our experiences, we can overcome them and build better tools and processes. Thanks for reading, and we hope this article has been helpful! Keep those milestones on track, and let's look forward to a fix from Leantime soon!