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
This reflects how we currently distributed our efforts to supporting the
different platforms and clarifies which things get run by the Nushell
team and which rely on the help of third-parties or individual
contributors.
Feel free to propose improvements, as long as they can be backed up by
implemented practice as a result.
Add Dorothy — https://github.com/bevry/dorothy — to the supported by
section. Dorothy is a dotfile ecosystem that enables a cross-shell and
cross-operating system dotfile experience. Allowing you to easily switch
to Nu, while keeping your existing env configuration, and allowing you
to write Nu commands that are accessible to other shells.
Dorothy now has CI testing for its Nu integration.
I would personally propose to remove the progress board table from our
README.
At the stage where we are at right now with most items in a pre-stable
stage I don't think it is a good use of README real estate anymore. It
hasn't been updated in over 7 months for a single item and older than a
year for most boxes.
For upcoming users the list doesn't present detailed enough explanations
of potential pitfalls and may be more confusing by mentioning features
that are not really present (e.g. paging). Generally I have the
impression that the community generally helps raise awareness about the
limitations of the pre-1.0 state together with our release notes that
try to highlight the pace of breaking or evolving changes.
Potential users are probably best served by additional links to learn
more about our features and generally improved documentation and
community tutorials
For contributors that want to look for areas to help out, this view is
both not granular enough for real guidance and is maybe even actively
harmful in highlighting areas we don't prioritize for 1.0 stability
(e.g. notebook integration)
Contributors are probably better served by our planned write-ups around
the 1.0 roadmap and updating GitHub Kanban/project boards.
# Description
i've almost always wanted to clean up the root of the repo, so here is
my take at it, with some important advice given by @fdncred 😌
- `README.release.txt` is now gone and directly inline in the
`release-pkg` script used in the `release` *workflow*
- `build.rs` has been moved to `scripts/` and its path has been changed
in
[`Cargo.toml`](https://github.com/amtoine/nushell/blob/refactor/clean-root/Cargo.toml#L3)
according to the [*Build Scripts*
section](https://doc.rust-lang.org/cargo/reference/build-scripts.html#build-scripts)
of *The Cargo Book*
- i've merged `images/` into `assets/` and fix the only mention to the
GIF in the README
- i've moved the `docs/README.md` inside the main `README.md` as a new
[*Configuration*
section](https://github.com/amtoine/nushell/tree/refactor/clean-root#configuration)
- the very deprecated `pkg_mgrs/` has been removed
- all the `.nu`, `.sh`, `.ps1` and `.cmd` scripts have been moved to
`scripts/`
### things i've left as-is
- all the other `.md` documents
- the configuration files
- all the Rust and core stuff
- `docker/`
- `toolkit.nu`
- the `wix/` diretory which appears to be important for `winget`
# User-Facing Changes
scripts that used to rely on the paths to some of the scripts should now
call the scripts inside `scripts/` => i think this for the greater good,
it was not pretty nor scalable to have a bunch of scripts in the root of
our main `nushell` 😱
*i even think we might want to move these scripts outside the main
`nushell` repo*
maybe to `nu_scripts` or some other tool 👍
# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- ⚫ `toolkit test`
- ⚫ `toolkit test stdlib`
# After Submitting
```
$nothing
```
# Description
Let's see if we don't run out of disk space as quickly again
This reverts commit 0e496f900d.
(#8677)
# User-Facing Changes
<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->
# Tests + Formatting
Same coverage setup as before
# Description
_(Thank you for improving Nushell. Please, check our [contributing
guide](../CONTRIBUTING.md) and talk to the core team before making major
changes.)_
_(Description of your pull request goes here. **Provide examples and/or
screenshots** if your changes affect the user experience.)_
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
- `cargo run -- crates/nu-utils/standard_library/tests.nu` to run the
tests for the standard library
> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
# Description
The coverage testing on CI has been broken for at least a week. It looks
like we might have to do some work, but for now, disabling it so we
don't give bad stability info to contributors.
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
- `cargo run -- crates/nu-utils/standard_library/tests.nu` to run the
tests for the standard library
> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
# Description
Take 2...
_(Thank you for improving Nushell. Please, check our [contributing
guide](../CONTRIBUTING.md) and talk to the core team before making major
changes.)_
_(Description of your pull request goes here. **Provide examples and/or
screenshots** if your changes affect the user experience.)_
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
# Description
The showcase repo has some cool material in it that I think is valuable
for our readers developers. Giving it a bit more exposure by putting it
our Readme will allow more folks to know this is yet another valuable
resource. I learned about this today from Darren and thought it would be
good to allow others the same opportunity to find it easier as well...
_(Thank you for improving Nushell. Please, check our [contributing
guide](../CONTRIBUTING.md) and talk to the core team before making major
changes.)_
_(Description of your pull request goes here. **Provide examples and/or
screenshots** if your changes affect the user experience.)_
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
Quicklinks to metrics. When we are proud to display them as badges,
let's show of the underlying statistics as well. Also helpful to quickly
get to the actions.
# Description
Broken link
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
# Description
_(Thank you for improving Nushell. Please, check our [contributing
guide](../CONTRIBUTING.md) and talk to the core team before making major
changes.)_
_(Description of your pull request goes here. **Provide examples and/or
screenshots** if your changes affect the user experience.)_
# User-Facing Changes
_(List of all changes that impact the user experience here. This helps
us keep track of breaking changes.)_
# Tests + Formatting
Don't forget to add tests that cover your changes.
Make sure you've run and fixed any issues with these commands:
- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass
# After Submitting
If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
* Clean up README
* Update CONTRIBUTING.md
* Another pass over the README. Table of contents, more install info
* add a little extra features definition
* fix Winget instructions
* Change winget instructions to nushell (easier to remember)
Co-authored-by: Darren Schroeder <343840+fdncred@users.noreply.github.com>
