1
0
mirror of https://github.com/nushell/nushell.git synced 2025-01-11 16:58:41 +01:00
nushell/devdocs/FAQ.md
Stefan Holderbach ffb80b8873
Curate developer documentation in tree ()
This is still work in progress. But let's start somewhere.

Goal for this being in the repo is to make sure we update it more
frequently than the
https://github.com/nushell/nushell.github.io/tree/main/contributor-book


- Add folder for in-repo developer documentation
- Move PLATFORM_SUPPORT into devdocs
- Move our rust style to devdocs
- Use nushell code formatting in CONTRIBUTING
- Add FAQ file for developers with example questions
- Describe error handling best practices
2023-11-21 18:12:00 +01:00

1.8 KiB

Frequently asked question for developers

Let's collect some questions a lot of Nushell contributors have.

  • How do I do....?
  • Why do I need to do certain things a certain way?

Let's keep the answers concise and up to date (or general enough) to remain relevant

How do I properly test my feature or bugfix?

TODO (Probably fork out into its own file)

I want to report an error to the user

Approximate flow:

  1. Are you reporting the error in the parser/static checking phase?
    • Use nu_protocol::ParseError variants
    • Follow the logic used in the context as we need to collect multiple errors for a good IDE experience
  2. Pick the right nu_protocol::ShellError variant
    • Does a matching existing variant fit your need? (go to references of the ShellError variant for inspiration)
    • Check what context the miette macros add during formatting! (go to definition of ShellError)
    • If it is a one-of specific error, consider using a generic variant
    • Else add a new class of errors
      • add the necessary Span information
      • general shared error text, to inform and point to a resolution
      • dynamic information gathered from the error site
      • Don't use a tuple enum variant, named structs going forward only!
  3. Are you in a command?
    • return Err(ShellError::...) and you're done in a Command::run
  4. Do you want to report a warning but not stop execution?
    • NEVER println!, we can write to stderr if necessary but...
    • good practice: nu_protocol::cli_error::report_error or report_error_new
      • depending on whether you have access to a StateWorkingSet
    • if only relevant to in the field debugging: log-crate macros.

How do I check an environment variable?

TODO

WTF is PipelineMetadata?

TODO