Ways To Get Feedback Prioritized

Where To Send Feedback gives tips on good feedback.

If you feel like your feedback isn't being addressed, here are some ways to make it more actionable.

OSH Compatibility Feature Requests

In theory, we would implement everything! In practice, we have to prioritize feature requests.

(Note that bugs/divergences from sh/bash are usually given the highest priority.)

Which programs use the missing feature?

We are trying to make this list bigger: Shell Programs That Run Under OSH

And as of 2024, also run some hairy Nix scripts.

To get your request prioritized, it's helpful to explain which scripts use a given feature, e.g. exec -a

Provide Failing Spec Tests

This definitely helps -- writing tests is half the battle!

TODO: show examples of PRs with failing spec tests.

See Spec Tests and Contributing for how to write, and run spec test. Definitely post a message on Zulip if you need help!

Provide a Patch, Including Tests!

The best possibility! It's OK to make it "quick and dirty", as long as it works. I can help with the style and linting, etc. See Contributing

YSH Design Feedback

Show Real Code You've Written - What does it look like before, and after?

This puts your problem in context.

Ideally, the code should work and have runnable tests.

Show what the code looks currently, and after the proposed change.

Reference the Project's Goals

Show how it applies to examples from

• Sketches of YSH Features
• #language-design > 16 Use Cases for Blocks / Reflection

Familiarize yourself with YSH idioms and concepts

e.g. Interior vs. Exterior

(There is often a simpler "exterior" way to solve a problem -- Oils is exterior-first)

Provide a Proof of Concept Implementation

This is the best way to get feedback prioritized, but the highest effort.

You may want to start a discussion before doing this.

Reference issues that other people have had

If there's a problem, you're unlikely to be the only one to experience it!

Looking through the issue tracker or Zulip for similar issues can help support your feedback.

Reference Existing Language Designs

Compare and contrast

• Other shells
• Python, JS, Ruby
• Perl, PHP
• Lisps
• etc.

Reference Existing Literature on Programming Languages

• (But summarize the relevant parts)
• Define the terms you're using, and use standard terminology where possible

Be Familiar with how Oils is Implemented

• e.g. a value.Place is a (name, stack frame) tuple, and setValue() must occur in a lower stack frame. It can't occur in a higher one.

Write a Clear, Crisp Document

This might be the last resort, but could help.

Crisp code examples are essential.

Explain your feedback to a friend, and have them write it up in their own words

Does it make sense?

Is it actionable?

(The real last resort!)