diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30951f1..139c54d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,3 +26,10 @@ When changing a utility's behavior, prefer landing the change in the relevant upstream project first and then updating the submodule here. Windows-specific glue, packaging, and the multi-call binary wrapper live in this repo and are fair game for direct PRs. + +## Windows-native commands + +For Windows-native commands that are not directly provided by the upstream +submodules, see [Windows-native command notes](docs/windows-native-commands.md) +before opening an implementation PR. In general, please open an issue first so +the command scope and option support can be agreed on. diff --git a/docs/windows-native-commands.md b/docs/windows-native-commands.md new file mode 100644 index 0000000..7c42067 --- /dev/null +++ b/docs/windows-native-commands.md @@ -0,0 +1,22 @@ +# Windows-Native Command Notes + +Some commands may need a small Windows-native implementation when the upstream +submodules do not provide a usable Windows backend. + +Before adding a new command, please open an issue first so maintainers can agree +on the command scope and option support. + +Prefer small, script-friendly commands that are commonly available by default on +Linux or macOS and can be implemented on Windows with clear, documented +approximations. Interactive, non-default, or broad system-management tools should +be discussed first because they can add significant maintenance cost. + +For GNU-compatible options: + +- Define options to match the GNU interface and upstream behavior where + practical. +- Implement options that can reasonably work on Windows, even if approximated. +- Return an error for options that cannot work on Windows but are important to + the command's behavior. +- Document Windows-specific approximations or unsupported behavior near the + option definitions, or in user-facing docs when needed.