Overhaul CONTRIBUTING document (#1103)

tj · Nov 11, 2023 · 7a65311 · rasa · Nov 11, 2023 · hyperupcall
1 parent 186bbdc
commit 7a65311
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 29 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,22 +1,40 @@
-## Your new git-extra command should support
+# Contributing
 
-* OSX, Linux, BSD (You may need to browse their man page)<sup>*</sup>
-* Bash 3.2+ (If you aren't sure, see [the Bash changelog](https://www.tldp.org/LDP/abs/html/bash2.html))
-* Git 2.1+
+Thanks for contributing! Please read this document before you make a PR.
 
-<sup>*</sup>If you aren't able to test your new command on a platform,
-make that clear in your PR and someone else may be able to test it on their system.
+## Supported Platforms
 
-## To submit a new command, you should
+Any changes must support the following platforms:
 
-Let's assume your new command is named `foo`.
+- macOS
+- Linux
+- OpenBSD (You may need to browse their man page)
+
+Your change must also be compatible with the dependency constraints that we specify in [Installation](./Installation.md). If you aren't sure if a feature is compatible, check the manual or release notes. For example, the Bash changelog is [here](https://git.savannah.gnu.org/cgit/bash.git/tree/NEWS?h=devel).
+
+If you aren't able to test your new command on a platform, make that clear in your PR; someone else may be able to test it on their system.
+
+## Testing
+
+We now have a testing suite. Run it with `make test`.
+
+It uses the following dependencies (same or later versions):
+
+- `python==3.10`
+- `pytest==7.4.0`
+- `GitPython==3.1.36`
+
+## Adding a New Command
+
+Let's say you wish to add a new command. Assuming your new command is named `foo`:
 
 1. Write a bash script under `./bin` called `git-foo`. The script should be started with `#!/usr/bin/env bash`.
 2. Read `./man/Readme.md` and write documentation for `git-foo`.
 3. Don't forget to introduce it in `Commands.md`.
 4. Update `./etc/git-extras-completion.zsh`. Just follow existing code.
 5. (Optional) Update `./etc/bash_completion.sh`.
 6. (Optional) Update `./etc/git-extras.fish`.
-7. Run `./check_integrity.sh foo` to check if all done.
+7. (Optional) Add a test under `./tests`.
+8. Run `./check_integrity.sh foo` to check if all done.
 
 You are welcome to open up an issue to discuss new commands or features before opening a pull request.
diff --git a/Installation.md b/Installation.md
@@ -1,14 +1,13 @@
-# Installing git-extras
+# Installation
 
 ## Dependencies
 
 Some commands require extra dependencies which are unavailable in some platforms.
-You may need to install them manually.
+You may need to install them manually. They are:
 
-Those dependencies are listed below:
-
-* column
 * bash 4.0+
+* Git 2.17+
+* `column`
 
 If `bash --version` shows a lower version, you need to update it.
 For example, the default bash in Mac is usually too old and you may need to update it via `brew install bash`.
@@ -36,6 +35,7 @@ $ sudo dnf install git-extras
 ### openSUSE
 
 Substitute your openSUSE version in the command below (in this case we are considering openSUSE Leap 15.2):
+
 ```bash
 $ sudo zypper ar https://download.opensuse.org/repositories/devel:/tools:/scm/openSUSE_Leap_15.2/devel:tools:scm.repo
 ```
@@ -68,7 +68,6 @@ $ nix-env -i git-extras
 
 [Abdullah](https://github.com/AWAN) has written a [Pkgfile](https://abdullah.today/ports/git-extras/Pkgfile) for his beloved [distro](https://crux.nu).
 
-
 ### Homebrew
 
 ```bash
@@ -77,7 +76,6 @@ $ brew install git-extras
 
 Installing from Homebrew will not give you the option omit certain `git-extras` if they conflict with existing git aliases. To have this option, build from source.
 
-
 ### Arch Linux
 
 * [git-extras](https://aur.archlinux.org/packages/git-extras/)
@@ -87,6 +85,7 @@ Installing from Homebrew will not give you the option omit certain `git-extras`
 
 First, please install `Git for Windows 2.x` from 'https://github.com/git-for-windows/git/releases'.
 Second, clone the `git-extras` repo into any folder you like.
+
 ```bash
 git clone https://github.com/tj/git-extras.git
 # checkout the latest tag (optional)
@@ -148,7 +147,7 @@ If you want to relocate the bulk of the installation but still have configuratio
 files installed to the system `/etc` dir or other alternate location, you can
 specify `SYSCONFDIR` in addition to `PREFIX`.
 
-```
+```sh
 $ sudo make install PREFIX=/usr/local SYSCONFDIR=/etc
 ```
 
@@ -165,6 +164,7 @@ curl -sSL https://raw.githubusercontent.com/tj/git-extras/main/install.sh | sudo
 ## Installing as Zsh plugin
 
 [ZInit](https://github.com/zdharma/zinit) can install git-extras by using:
+
 ```zsh
 zinit ice as"program" pick"$ZPFX/bin/git-*" src"etc/git-extras-completion.zsh" make"PREFIX=$ZPFX"
 zinit light tj/git-extras

diff --git a/Readme.md b/Readme.md
@@ -18,18 +18,6 @@ Go to the [Commands](Commands.md) page for basic usage and examples.
 
 __GIT utilities__ -- repo summary, repl, changelog population, author commit percentages and more
 
-## Test
-
-Nowaday the continues integrations test is coming and you can access it via the `make test` easily.
-
-The CI depends on
-
-* `python==3.10`
-* `pytest==7.4.0`
-* `GitPython==3.1.36`
-
-So the version or higher is recommended.
-
 ## Contributing
 
 Interested in contributing? Awesome!