search

craeyeons / pe

0 stars 0 forks source link

Help command formatting issue. #9

Open craeyeons opened 1 year ago

craeyeons commented 1 year ago

image.png

Steps to reproduce:

  1. execute help or
  2. "any command here" -h

I am quite sure that this is not intentional, and it is a formatting issue. However, this renders the help feature useless, and forces the user to refer to the user guide.

nus-se-script commented 1 year ago

Team's Response

Hi, thanks for the bug report!

We tried to reproduce this bug on our end and it appears to be okay on our end. Here's what the expected UI should look like after you run the help command.

photo1668237581.jpeg

However, we did some additional research to investigate the root cause of this issue. It appears that the problem is not with our application but the system's environment variables. In particular, we use the picocli parsing library, which decides whether to show or hide ANSI characters depending on the system's environment variables.

For most users (like all of our team members and other testers in the PE-D), it causes no issues because the environment variables don't conflict with picocli and ANSI characters are hidden by default.

However, in some cases when certain environment variables are set to specific values (such as CLICOLOR = 1), it leads to the issue that you experienced (ANSI characters are being shown directly). This only affects mac users who have changed the default environment variables (using installations such as oh-my-zsh or similar) and with OS versions > 10.5 (as the default shell provided in MacOS before 10.5 was bash).

Before running java -jar truthtable.jar, run export CLICOLOR = 0 and it should work correctly.

Keeping all this in mind, let me explain our rationale for marking this issue as a low severity documentation bug (as opposed to a high severity functionality bug):

  1. The issue affects a small fraction of users (those who have modified their environment variables and in particular, CLICOLOR or other similar)
  2. This issue doesn't make the application unusable. This only affects the help command and using the help flags. In either case, the User Guide serves as an extensive manual for users to understand commands if they are facing this issue. The help command is not the main feature of this application and it is unlikely to be used many times by a user (although a beginner may want to use help often as he/she may forget the commands, in which case the UG still exists to help the user)

However, your issue is still valid and we accept that we did not try it on this special subset of mac users who have changed their environment variables.

Since the issue can be easily fixed by adding the above instruction (to run export CLICOLOR = 0) in the UG for this specific group of users, we feel this is a documentation bug. Since it does not cause major troubles in terms of the functionality of the actual commands (like add, edit, etc.), we feel this is a low severity bug. Moreover, the link to the UG is also included in the help message shown when the other formatting is incorrect so the help command does provide some guidance to the user on how to get help.

Taken from the module's website: "A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only."

Here are some of the websites we consulted while investigating this bug:

  1. https://picocli.info/#_heuristics_for_enabling_ansi
  2. https://www.folkstalk.com/tech/python-terminal-colour-with-code-examples/

Hope you understand our rationale and justifications.

Have a nice reading week ahead!

The 'Original' Bug

[The team marked this bug as a duplicate of the following bug]

[UI] Result display doesn't display symbols

image.png

Command usages in the result display do not accurately display the symbols needed.

[original: nus-cs2103-AY2223S1/pe-interim#751] [original labels: type.FunctionalityBug severity.VeryLow]

Their Response to the 'Original' Bug

[This is the team's response to the above 'original' bug]

Hi, thanks for the bug report!

TLDR: we accept your bug as a low severity documentation bug instead of functionality bug. The rest of this comment just explains our investigation process if you're interested (please ignore the labels given in the explanations as we went through a long journey involving many changes and considerations, i.e., the comments regarding severity and type may be outdated and should be ignored.). The only reason we are keeping this long comment is because it's a very interesting bug and it was super cool to figure out the root cause :)

Alert: long explanation ahead

We tried to reproduce this bug on our end and it appears to be okay on our devices. Here's what the expected UI should look like after you run the help command.

photo1668237581.jpeg

However, we did some additional research to investigate the root cause of this issue. It appears that the problem is not with our application but the system's environment variables. In particular, we use the picocli parsing library, which decides whether to show or hide ANSI characters depending on the system's environment variables.

For most users (like all of our team members and other testers in the PE-D), it causes no issues because the environment variables don't conflict with picocli and ANSI characters are hidden by default.

However, in some cases when certain environment variables are set to specific values (such as CLICOLOR = 1), it leads to the issue that you experienced (ANSI characters are being shown directly). This only affects Mac users who have changed the default environment variables (using installations such as oh-my-zsh or similar) and with OS versions > 10.5 (as the default shell provided in MacOS before 10.5 was bash).

Before running java -jar truthtable.jar, run export CLICOLOR = 0 and it should work correctly.

Keeping all this in mind, let me explain our rationale for marking this issue as a documentation bug (as opposed to a functionality bug):

  1. The issue affects a small fraction of users (those who have modified their environment variables and in particular, CLICOLOR or other similar)
  2. This issue doesn't make the application unusable. This only affects the help command and using the help flags. In either case, the User Guide serves as an extensive manual for users to understand commands if they are facing this issue. The help command is not the main feature of this application and it is unlikely to be used many times by a user (although a beginner may want to use help often as he/she may forget the commands, in which case the UG still exists to help the user)

However, your issue is still valid and we accept that we did not try it on this special subset of mac users who have changed their environment variables.

Since the issue can be easily fixed by adding the above instruction (to run export CLICOLOR = 0) in the UG to aid this specific group of users, we feel this is a documentation bug. Since it does not cause major troubles in terms of the functionality of the actual commands (like add, edit, etc.), we feel this is a low severity bug. Moreover, the link to the UG is also included in the help message shown when the other formatting is incorrect so the help command does provide some guidance to the user on how to get help.

Here are some of the websites we consulted while investigating this bug:

  1. https://picocli.info/#_heuristics_for_enabling_ansi
  2. https://www.folkstalk.com/tech/python-terminal-colour-with-code-examples/

Edit: after some more investigation, we found that there is no issue when you open the jar file by double clicking rather than running java -jar truthtable.jar. We are aware that the module website mentions to use double clicking as a last resort, but our UG explicitly asks users to open the jar file by double clicking. If you have the correct Java version (11) and JDK (zulu), there is no issue with the help commands if you open the application by double clicking the jar file. Thus, there is no issue with our application if instructions from the UG are carefully followed.

Hope you understand our rationale and justifications.

Have a nice reading week ahead!

Items for the Tester to Verify

:question: Issue duplicate status

Team chose to mark this issue as a duplicate of another issue (as explained in the Team's response above)

Reason for disagreement: [replace this with your explanation]

:question: Issue type

Team chose [type.DocumentationBug] Originally [type.FunctionalityBug]

Reason for disagreement: image.png

The feature does not behave as expected. Hence I think it is a functionality bug.

export CLICOLOR = 0 is something that came with the realisation of the functionality bug.

:question: Issue severity

Team chose [severity.Low] Originally [severity.High]

Reason for disagreement: Thanks for taking the time to investigate the issue. However, it rendered all help commands to be useless on my device.

True, I agree that it is impossible to check for all devices with different configurations and installations.

However, I believe this is the risk that you chose to bore when using picocli. The issue would not have arose if picocli was not used.

This issue doesn't make the application unusable. This only affects the help command and using the help flags. In either case, the User Guide serves as an extensive manual for users to understand commands if they are facing this issue. The help command is not the main feature of this application and it is unlikely to be used many times by a user (although a beginner may want to use help often as he/she may forget the commands, in which case the UG still exists to help the user)

I think the scope of severity.High is not the application as a whole, but this specific feature.

Hence the existence of a user guide or any other backup solution does not reduce the severity of this issue.

image.png

Edit: after some more investigation, we found that there is no issue when you open the jar file by double clicking rather than running java -jar truthtable.jar. We are aware that the module website mentions to use double clicking as a last resort, but our UG explicitly asks users to open the jar file by double clicking. If you have the correct Java version (11) and JDK (zulu), there is no issue with the help commands if you open the application by double clicking the jar file. Thus, there is no issue with our application if instructions from the UG are carefully followed.

You are expected to have the testers run the programme using java - jar truthtable.jar instead of double clicking. Unfortunately it is your user guide that does not abide to the module's requirements.

image.png