Improve UX for Swift Package Manager CLI

Hi everyone :wave:,
@tomerd @NeoNacho

I'm Ahmad a computer engineering student from Egypt. I develop iOS apps and am interested in competitive programming. This is my website: ahmdyasser. I'm super interested to participate in GSoC this year to make SPM a better tool and used seamlessly by the users.

4 Likes

Hi @ahmdyasser and thank you for your interest in the project.

SwiftPM is Swift's dependency management tool and can be used from the command line and from IDEs.
The project focus is on improving the command line experience which boils down to two parts:

  1. Input: How users pass arguments, options, flags and get help around these.
  2. Output: How SwiftPM emits output to users which includes direct output, indirect output (side effects), progress, errors and warnings.

For user input, SwiftPM uses Swift Argument Parser (GitHub - apple/swift-argument-parser: Straightforward, type-safe argument parsing for Swift ) - a library that helps parse command line arguments.
Potential improvements in this context are mostly optimizing the definition of available command line arguments:

  • Audit inputs for consistency on language and style
  • Making options type safe
  • Logical grouping
  • Expanding and improving the help and usage explanations

For user output, SwiftPM outputs to the stdout and stderr, including progress indicators for operations like downloading or fetching dependencies.

When stdout is connected to a tty and the terminal supports it, SwiftPM uses ANSI escape codes to provide interactive progress-oriented output. When connected to a pipe, the output tends to be more focused on the actions taken and less on progress, since plain output is primarily used in Continuous Integration environments where issues have to be investigated after-the-fact.

Potential improvements is this context include:

  • Audit output options for consistency (e.g. output format option)
  • Improved progress indicators
  • Improved duration tracking and reporting
  • For concurrent work, present output from active task per worker / thread
  • Provide additional contextual information for warnings and errors
  • Graphical output for dependency graphs
  • General modernization the output - adopting modern CLI UX/UI best practices
1 Like

Hi @tomerd, thanks for the reply.
I have a question. Is it possible to use colors in the SwiftPM CLI?
For example green for passed tests and red for failed ones. I'm also wondering if there is CLI guidelines Apple made? something like Apple Human Interface Guidelines.

Hello again @tomerd!
I have another question. Your proposed potential improvements for the input and the output. Do I have to implement all of them? or just the most important ones?

I also have come across a feature in many CLI tools like Git which is autocorrecting. It's an amazing addition to any CLI app for better UX and I was doing research to figure out how to implement it, but I've found that the responsible for this would be Swift Argument Parser, not SwiftPM. So, is it allowed to contribute to another repo -Swift Argument Parser- to give SwiftPM a better user experience?

Screenshot of autocorrecting in Git

When trying to make a typo it won't work in SwiftPM

Replying for Tom since he's away: yeah, I believe this would be acceptable and, in fact, welcome :slight_smile: If we need to improve argument parser to help with features we're interested in here we can totally do so.

As for this specific feature though, I believe it is implemented: Provide near-miss suggestions · Issue #2 · apple/swift-argument-parser · GitHub in Provide suggestions for unknown options by klaaspieter · Pull Request #10 · apple/swift-argument-parser · GitHub so for this specific thing I don't think we'd need to change argument parser.

1 Like

Hi @tomerd @ktoso, thanks a lot for the feedback!
@tomerd suggested some potential improvements and I have some questions about them.

  • Graphical output for dependency graphs

  • Audit inputs for consistency on language and style

    • can you give me more details about this?
  • Making options type-safe

    • (do you mean, for example, giving the user Y/n option to confirm the option?
  • Logical grouping

    • (what exactly should I group?)
  • Expanding and improving the help and usage explanations

    • I have done some research and I have some ideas for this, like displaying the most common flags and commands at the start of the help text and ranking them by the most common ones like the image below.
  • Improved progress indicators

    • does making indicators like the one in the image below is acceptable?
      image
  • There are also several general UX improvements I would love to hear your opinion about:

    • Using formatting in help text, bold headings make it much easier to scan.

    • Adding colors to highlight some text so the user notices it, or use red to indicate an error. SwiftPM already has the Color4 enum to change the color of the output, so we only have to know where to apply different colors related to the context.

The last question, this project is estimated to be 175 hours, should I design my timeline in my proposal for 4 weeks or more?

Thank y'all for bearing with me up to this point :smile:

2 Likes

As a user, progress indicators would be very welcome, even more so as a reusable separate module that could be used across command line programs in Swift.

2 Likes

Thanks a lot for the feedback, Alexis! If the mentors accepted the idea I would do it as you said: as a separate module for all Swift CLI programs.

While Tom is still out let me take a stab at few of those :slight_smile:


For reference, seems @Aciid ported one style of progress bar to swiftpm a while ago: swift-tools-support-core/ProgressAnimation.swift at main · apple/swift-tools-support-core · GitHub (via https://twitter.com/aciidb0mb3r/status/1512996018995965952 ).

Though the styles you posted also look nice :slight_smile:

It could also be interesting to look allowing plugins to report package progress: swift-evolution/0332-swiftpm-command-plugins.md at main · apple/swift-evolution · GitHub


I think this is about using "right words in the right contexts" like always saying package when we mean package, consistency of command names etc.

This is a rather specific design and implementation task regarding package plugins:

You'll notice they have options but they're not well typed. The idea for typed options is explained here in depth: swift-evolution/0303-swiftpm-extensible-build-tools.md at main · apple/swift-evolution · GitHub

Think about how some tasks and commands are logically of the same group swift build --help. I guess this could be about grouping them into logical groups? @tomerd or @abertelrud might have to clarify that one tho :)


Organizationally:

Yeah that sounds right. Please estimate for within the size of the project's proposed timeline :slight_smile:

3 Likes

Thanks a lot for the reply, it helped me a lot!
I have a question, can I send you or any of the mentors my final proposal to review before submitting it?

You can email it to me if you're unable to use the direct message feature on the forums.

Please don't forget to submit using the website though; final submissions must be on the website and directly emailed ones don't count. Tho we can provide some feedback.

1 Like