First of all, thank you for contributing. Any contribution is highly appreciated and welcome.
There's a simple philosophy behind the Spaceship:
- Show only what's needed. The prompt should not be overloaded, it shows only what user needs at the moment (current directory, git branch, etc).
- Work out of the box. The prompt should work right after installation without any additional configuration. Install it and use it.
- Be configurable. It works without configuration, but if a configuration is needed, it provides an easy-to-use interface for customization.
Please, keep this simple rules in mind while you're contributing to Spaceship.
- Fork this repo (click the fork button)
- Clone your fork to your working machine (via
- Update submodules in your fork (via
git submodule update --init --recursive)
- Make your changes. Check our API for more information (we suggest you to check out a new branch for changes).
- Test your code (via
- Add and commit your contributions
- Push your changes to your remote fork
- Open a pull-request to our primary repo
Spaceship supports most of the popular programming languages, runtimes, version managers, etc. If it doesn't support something that you need, feel free to open a pull request, but answer these questions for yourself before:
Will it clutter the prompt?
Having too much in prompt looks ugly. your much space or be shown too often.
Is it worth to be aware of it?
Is value changes quite often so it needs to be shown in prompt? Would it be useful for other users? Maybe there's a reason to execute a command instead of cluttering prompt.
- Good: git status/branch, runtime version via version manager, etc
- Bad: version of language-specific framework, settled projects versions, etc
Will it slow down the prompt?
Every additional section will slow down the prompt a little bit. If your section performs any heavy checkings, find a way to make it faster or consider using an alias instead of creating a new section.
- Good: check if command exists, check the value of environment variable
- Bad: network requests, reading large files, etc
What is the naming convention for options?
All options of prompt follow a specific pattern so that it is easy to remember:
SPACESHIP_SECTION_<OPTION>[_PROPERTY]. The rule is simple: when naming new properties, keep unique parts of the name to the end.
COLORis option and
When updating documentation for your section, make sure the markdown document is being properly rendered by Github. Specifically, the following common pitfalls have already been discovered:
- Empty inline code block
` will only be rendered if you put at least one non-breaking whitespace " " inside, like so: ``
- Leading and trailing whitespaces in inline code blocks will be stripped, to indicate that a whitespace is present, use the middot symbol
·, like so:
Thanks for reading this contribution guide! Happy hacking!