From 7a65311b1c7e074760c61aa2ebc0f8bd3665bc51 Mon Sep 17 00:00:00 2001 From: Edwin Kofler Date: Fri, 10 Nov 2023 20:50:50 -0800 Subject: [PATCH] Overhaul CONTRIBUTING document (#1103) --- CONTRIBUTING.md | 36 +++++++++++++++++++++++++++--------- Installation.md | 16 ++++++++-------- Readme.md | 12 ------------ 3 files changed, 35 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a03fd6..019f791 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,32 @@ -## Your new git-extra command should support +# Contributing -* OSX, Linux, BSD (You may need to browse their man page)* -* 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. -*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`. @@ -17,6 +34,7 @@ Let's assume your new command is named `foo`. 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 index ec736ec..578cf4c 100644 --- 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 index 21d8644..885499a 100644 --- 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!