Skip to content

docs: clarify project scope #93

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
a-rookie-of-C-language wants to merge 1 commit into from
+50 −0
Closed

docs: clarify project scope #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,41 @@ Otherwise, you can of course always open an issue for us to look into.
Please open a new issue for any feature requests you have in mind.
Since most of the behavior comes from upstream (`deps/`), new features are usually best discussed (and landed) upstream first.

## Project scope

This repository packages Unix-style command-line utilities for native Windows.
Most commands should come from one of the bundled upstream projects:

* `deps/coreutils`: GNU coreutils-compatible utilities.
* `deps/findutils`: `find` and `xargs`.
* `deps/grep`: `grep`, `egrep`, and `fgrep`.

We are not limited to GNU coreutils only. Small Windows-native commands can be
accepted when they make the Unix-like command set more useful on Windows.

The usual bar is:

* It has a close equivalent on Linux or macOS.
* That equivalent is commonly installed by default.
* People commonly use it in scripts or ordinary shell sessions.
* The Windows implementation is small enough to maintain here.
* Any Windows-specific behavior can be explained clearly.

For example, a small command such as `which` may fit this repository. So may a
Windows backend for a command that already exists upstream but is currently
Unix-only.

Commands are usually out of scope when they are not installed by default on
common Unix-like systems, are rarely used, depend on POSIX-only concepts that do
not translate to Windows, or require a large interactive terminal UI. `top`, for
example, is out of scope for now: it is mostly an interactive TUI, not a
scripting utility.

When a utility already belongs to an upstream uutils project, prefer adding or
fixing the Windows backend upstream first. Code in this repository should be for
Windows-specific glue, packaging, the multi-call wrapper, or small native
commands that do not have a better upstream home.

## Code changes

This repository is a Microsoft-maintained Windows build of upstream coreutils.
Expand Down
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
<h3 align="center">
<a href="#install">Install</a>
<span> · </span>
<a href="#project-scope">Project scope</a>
<span> · </span>
<a href="#shell-conflicts">Shell conflicts</a>
<span> · </span>
<a href="#windows-caveats">Windows caveats</a>
Expand All @@ -26,6 +28,19 @@ Each command supports the standard `--help` flag for full syntax and options.

<br/>

## Project scope

This project ships Unix-style command-line utilities for native Windows use,
mostly from `uutils/coreutils`, `uutils/findutils`, and `uutils/grep`. We may
also include small Windows-native commands when they match tools that are
commonly available by default on Linux or macOS and are useful in scripts or
normal shell use. Large interactive tools are out of scope for now.

See [`CONTRIBUTING.md`](./CONTRIBUTING.md#project-scope) for the full scope
guidelines.

<br/>

## Install

Install Coreutils for Windows with WinGet:
Expand Down