From 3e9646e694a28a52187964f9d89befb44dae1f6d Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sat, 15 Jul 2023 12:30:45 +0200 Subject: [PATCH 1/8] feat: `CONTRIBUTING.md` --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..639704674 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +Contributions and Pull Requests are very welcome. If you are planning to implement a larger feature please open an issue +prior to minimize the risk of multiple people working on the same thing simultaneously; or to discuss some specifics of +the feature. + +Neogit draws heavy inspiration from [Magit](https://magit.vc/), but aims to be its own thing. Many of our features are +inspired by Magit, such as the branch keybindings. + + +## Architecture + +- [`./lua/neogit/`] + - [`./lua/neogit/lib/`] Contains various git and filesystem abtractions + - [`./lua/neogit/lib/git/`] High level git wrappers for commont commands such as branches, fetch. These are also used to + supply the status buffer + - [`./lua/neogit/lib/git/cli.lua`] Builder like pattern for constructing git cli invocations + - [`./lua/neogit/lib/git/repository.lua`] Modules from `git/` for updating the statusbuffer + - [`./lua/neogit.lua`] + +Neogit uses its own UI drawing library for drawing columns and rows of text. + +### Making a new view + +Neogit's views, such as the `commit` buffer, `log` graph buffer, etc are located in [`./lua/neogit/buffers/`]. They +are split in a `init.lua` for creating the buffer and setting up keymaps and actions, and `ui.lua` for rendering the +buffer. The split is such that it is easier to get an overview of how the buffer will *look* without the clutter of git +commands and actions. + +Opening a view is typically done through a *popup* which allows you to configure options before invoking the view. + +These reside inside [`./lua/neogit/popups/`], and are split into `init.lua` and `actions.lua` for the setup and keybindings, and the git commands to execute, likewise intended to get an overview of the options and keybindings for the popup in `init.lua` without concerning yourself with the git commands and parsing in `actions.lua`. + +## Code Standards + +### Testing + +Neogit is tested using [Plenary](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). + +A [Makefile](./Makefile) is set up to run tests. + +```sh +make test +``` + +### Linting + +Additionally, linting is enforced using `selene` to catch common errors, most of which are also caught by +`lua-language-server`. + +```sh +make lint +``` + +### Formatting + +`stylua` is used for formatting. This formatting is slightly different from the built in formatting for +`lua-language-server`. From 7e6faaacde28c77a162a5f0dfa7de2c68bd6dc35 Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sat, 15 Jul 2023 12:37:55 +0200 Subject: [PATCH 2/8] fix: typos --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 639704674..6b6a2abde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,11 +11,11 @@ inspired by Magit, such as the branch keybindings. ## Architecture - [`./lua/neogit/`] - - [`./lua/neogit/lib/`] Contains various git and filesystem abtractions - - [`./lua/neogit/lib/git/`] High level git wrappers for commont commands such as branches, fetch. These are also used to + - [`./lua/neogit/lib/`] Contains various git and filesystem abstractions + - [`./lua/neogit/lib/git/`] High level git wrappers for common commands such as branches, fetch. These are also used to supply the status buffer - [`./lua/neogit/lib/git/cli.lua`] Builder like pattern for constructing git cli invocations - - [`./lua/neogit/lib/git/repository.lua`] Modules from `git/` for updating the statusbuffer + - [`./lua/neogit/lib/git/repository.lua`] Modules from `git/` for updating the status buffer - [`./lua/neogit.lua`] Neogit uses its own UI drawing library for drawing columns and rows of text. From dcaaeb1e5864a16ba23af83773a3065af74b6ec4 Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sat, 15 Jul 2023 12:51:14 +0200 Subject: [PATCH 3/8] feat(contributing): `Getting Started` and `Testing` --- CONTRIBUTING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b6a2abde..e80b1f934 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,12 +31,26 @@ Opening a view is typically done through a *popup* which allows you to configure These reside inside [`./lua/neogit/popups/`], and are split into `init.lua` and `actions.lua` for the setup and keybindings, and the git commands to execute, likewise intended to get an overview of the options and keybindings for the popup in `init.lua` without concerning yourself with the git commands and parsing in `actions.lua`. +## Getting Started + +If you are using [Lazy.nvim](`https://github.com/folke/lazy.nvim`) you can configure it to prefer sourcing plugins from +a local directory instead of from git. + +Simply clone Neogit to your project directory of choice to be able to use your local changes. See [`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and [`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. + ## Code Standards ### Testing Neogit is tested using [Plenary](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). +It uses a *Busted* style testing, where each lua file inside [`./tests/{test_name}_spec.lua`] is run. + +When adding new functionality we strongly encourage you to add a test spec to ensure that the feature works and remains +working when new functionality is tacked on. + +If you find or fix a bug, it is desired that you add a test case for the bug to ensure it does not occur again in the future, and remains *fixed*. + A [Makefile](./Makefile) is set up to run tests. ```sh From 9695afd5e921ca935914ca209d7e4f492d2c1c41 Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sun, 16 Jul 2023 10:49:59 +0200 Subject: [PATCH 4/8] chore: add popups section following #601 --- CONTRIBUTING.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e80b1f934..fc34b0004 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,8 +4,8 @@ Contributions and Pull Requests are very welcome. If you are planning to impleme prior to minimize the risk of multiple people working on the same thing simultaneously; or to discuss some specifics of the feature. -Neogit draws heavy inspiration from [Magit](https://magit.vc/), but aims to be its own thing. Many of our features are -inspired by Magit, such as the branch keybindings. +`Neogit` draws heavy inspiration from [`Magit`](https://magit.vc/), but aims to be its own thing. Many of our features are +inspired by `Magit`, such as the branch keybindings. ## Architecture @@ -16,13 +16,14 @@ inspired by Magit, such as the branch keybindings. supply the status buffer - [`./lua/neogit/lib/git/cli.lua`] Builder like pattern for constructing git cli invocations - [`./lua/neogit/lib/git/repository.lua`] Modules from `git/` for updating the status buffer - - [`./lua/neogit.lua`] + - [`./lua/neogit/popups/`] Contains all the popups and keybindings + - [`./lua/neogit/buffers/`] Contains all the buffer views, such as `commit_editor` or `log_view` -Neogit uses its own UI drawing library for drawing columns and rows of text. +`Neogit` uses its own UI drawing library for drawing columns and rows of text. ### Making a new view -Neogit's views, such as the `commit` buffer, `log` graph buffer, etc are located in [`./lua/neogit/buffers/`]. They +`Neogit`'s views, such as the `commit` buffer, `log` graph buffer, etc are located in [`./lua/neogit/buffers/`]. They are split in a `init.lua` for creating the buffer and setting up keymaps and actions, and `ui.lua` for rendering the buffer. The split is such that it is easier to get an overview of how the buffer will *look* without the clutter of git commands and actions. @@ -31,18 +32,21 @@ Opening a view is typically done through a *popup* which allows you to configure These reside inside [`./lua/neogit/popups/`], and are split into `init.lua` and `actions.lua` for the setup and keybindings, and the git commands to execute, likewise intended to get an overview of the options and keybindings for the popup in `init.lua` without concerning yourself with the git commands and parsing in `actions.lua`. +To access your new popup through a keybinding, add it to the table in [`./lua/neogit/popups/init.lua`] inside +`mappings_table`. This will enable you to access the popup through both the status buffer and help popup. + ## Getting Started If you are using [Lazy.nvim](`https://github.com/folke/lazy.nvim`) you can configure it to prefer sourcing plugins from a local directory instead of from git. -Simply clone Neogit to your project directory of choice to be able to use your local changes. See [`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and [`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. +Simply clone `Neogit` to your project directory of choice to be able to use your local changes. See [`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and [`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. ## Code Standards ### Testing -Neogit is tested using [Plenary](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). +`Neogit` is tested using [Plenary](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). It uses a *Busted* style testing, where each lua file inside [`./tests/{test_name}_spec.lua`] is run. From d9cda5ccd8c44b24af0e8c8946aa96e359bbf22e Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sun, 16 Jul 2023 10:53:00 +0200 Subject: [PATCH 5/8] chore: formatting --- CONTRIBUTING.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc34b0004..d7f101b52 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,16 +4,16 @@ Contributions and Pull Requests are very welcome. If you are planning to impleme prior to minimize the risk of multiple people working on the same thing simultaneously; or to discuss some specifics of the feature. -`Neogit` draws heavy inspiration from [`Magit`](https://magit.vc/), but aims to be its own thing. Many of our features are -inspired by `Magit`, such as the branch keybindings. +`Neogit` draws heavy inspiration from [`Magit`](https://magit.vc/), but aims to be its own thing. Many of our features +are inspired by `Magit`, such as the branch keybindings. ## Architecture - [`./lua/neogit/`] - [`./lua/neogit/lib/`] Contains various git and filesystem abstractions - - [`./lua/neogit/lib/git/`] High level git wrappers for common commands such as branches, fetch. These are also used to - supply the status buffer + - [`./lua/neogit/lib/git/`] High level git wrappers for common commands such as branches, fetch. These are also used + to supply the status buffer - [`./lua/neogit/lib/git/cli.lua`] Builder like pattern for constructing git cli invocations - [`./lua/neogit/lib/git/repository.lua`] Modules from `git/` for updating the status buffer - [`./lua/neogit/popups/`] Contains all the popups and keybindings @@ -30,45 +30,46 @@ commands and actions. Opening a view is typically done through a *popup* which allows you to configure options before invoking the view. -These reside inside [`./lua/neogit/popups/`], and are split into `init.lua` and `actions.lua` for the setup and keybindings, and the git commands to execute, likewise intended to get an overview of the options and keybindings for the popup in `init.lua` without concerning yourself with the git commands and parsing in `actions.lua`. +These reside inside [`./lua/neogit/popups/`], and are split into `init.lua` and `actions.lua` for the setup and +keybindings, and the git commands to execute, likewise intended to get an overview of the options and keybindings for +the popup in `init.lua` without concerning yourself with the git commands and parsing in `actions.lua`. To access your new popup through a keybinding, add it to the table in [`./lua/neogit/popups/init.lua`] inside `mappings_table`. This will enable you to access the popup through both the status buffer and help popup. ## Getting Started -If you are using [Lazy.nvim](`https://github.com/folke/lazy.nvim`) you can configure it to prefer sourcing plugins from +If you are using [`Lazy.nvim`](https://github.com/folke/lazy.nvim) you can configure it to prefer sourcing plugins from a local directory instead of from git. -Simply clone `Neogit` to your project directory of choice to be able to use your local changes. See [`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and [`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. +Simply clone `Neogit` to your project directory of choice to be able to use your local changes. See +[`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and +[`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. ## Code Standards ### Testing -`Neogit` is tested using [Plenary](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). +`Neogit` is tested using [`Plenary`](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). It uses a *Busted* style testing, where each lua file inside [`./tests/{test_name}_spec.lua`] is run. When adding new functionality we strongly encourage you to add a test spec to ensure that the feature works and remains working when new functionality is tacked on. -If you find or fix a bug, it is desired that you add a test case for the bug to ensure it does not occur again in the future, and remains *fixed*. +If you find or fix a bug, it is desired that you add a test case for the bug to ensure it does not occur again in the +future, and remains *fixed*. -A [Makefile](./Makefile) is set up to run tests. +A [`Makefile`](./Makefile) is set up to run tests. -```sh -make test -``` +```sh make test ``` ### Linting Additionally, linting is enforced using `selene` to catch common errors, most of which are also caught by `lua-language-server`. -```sh -make lint -``` +```sh make lint ``` ### Formatting From ecd39cca13352bb341f6ee1eeea7d554dd87c3c9 Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sun, 16 Jul 2023 10:55:20 +0200 Subject: [PATCH 6/8] fix: wording --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7f101b52..c469e64f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,7 @@ # Contributing -Contributions and Pull Requests are very welcome. If you are planning to implement a larger feature please open an issue -prior to minimize the risk of multiple people working on the same thing simultaneously; or to discuss some specifics of -the feature. +Contributions of all kinds are very welcome. If you are planning to implement a larger feature please open an issue +prior to minimize the risk of duplicate work, or to discuss some specifics of the feature; such as keybindings. `Neogit` draws heavy inspiration from [`Magit`](https://magit.vc/), but aims to be its own thing. Many of our features are inspired by `Magit`, such as the branch keybindings. From 2cb6e6b3959279e4aa3d0ac511109d3d6929bdb6 Mon Sep 17 00:00:00 2001 From: Tei Roberts Date: Sun, 16 Jul 2023 20:58:47 +0200 Subject: [PATCH 7/8] chore: make nouns stand out less --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c469e64f7..39a677046 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,8 +3,8 @@ Contributions of all kinds are very welcome. If you are planning to implement a larger feature please open an issue prior to minimize the risk of duplicate work, or to discuss some specifics of the feature; such as keybindings. -`Neogit` draws heavy inspiration from [`Magit`](https://magit.vc/), but aims to be its own thing. Many of our features -are inspired by `Magit`, such as the branch keybindings. +Neogit draws heavy inspiration from [Magit](https://magit.vc/), but aims to be its own thing. Many of our features +are inspired by Magit, such as the branch keybindings. ## Architecture @@ -22,7 +22,7 @@ are inspired by `Magit`, such as the branch keybindings. ### Making a new view -`Neogit`'s views, such as the `commit` buffer, `log` graph buffer, etc are located in [`./lua/neogit/buffers/`]. They +Neogit's views, such as the `commit` buffer, `log` graph buffer, etc are located in [`./lua/neogit/buffers/`]. They are split in a `init.lua` for creating the buffer and setting up keymaps and actions, and `ui.lua` for rendering the buffer. The split is such that it is easier to get an overview of how the buffer will *look* without the clutter of git commands and actions. @@ -41,7 +41,7 @@ To access your new popup through a keybinding, add it to the table in [`./lua/ne If you are using [`Lazy.nvim`](https://github.com/folke/lazy.nvim) you can configure it to prefer sourcing plugins from a local directory instead of from git. -Simply clone `Neogit` to your project directory of choice to be able to use your local changes. See +Simply clone *Neogit* to your project directory of choice to be able to use your local changes. See [`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and [`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. @@ -49,7 +49,7 @@ Simply clone `Neogit` to your project directory of choice to be able to use your ### Testing -`Neogit` is tested using [`Plenary`](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). +Neogit is tested using [`Plenary`](https://github.com/nvim-lua/plenary.nvim#plenarytest_harness). It uses a *Busted* style testing, where each lua file inside [`./tests/{test_name}_spec.lua`] is run. From 9a5e36abb736a0bc0b68d97c498aa4c21b53674c Mon Sep 17 00:00:00 2001 From: Tei Leelo Roberts Date: Mon, 17 Jul 2023 09:35:41 +0200 Subject: [PATCH 8/8] feat(contributing): logging --- CONTRIBUTING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39a677046..de57783e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,21 @@ Simply clone *Neogit* to your project directory of choice to be able to use your [`lazy-spec`](https://github.com/folke/lazy.nvim#-plugin-spec) and [`lazy-configuration`](https://github.com/folke/lazy.nvim#%EF%B8%8F-configuration) for details. +### Logging + +Logging is a useful tool for inspecting what happens in the code and in what order. Neogit uses +[`Plenary`](https://github.com/nvim-lua/plenary.nvim) for logging. + +Export the environment variables `NEOGIT_LOG_CONSOLE="sync"` to enable logging, and `NEOGIT_LOG_LEVEL="debug"` for more +verbose logging. + +```lua +local logger = require("neogit.logger") + +logger.fmt_info("This is a log message: %d", 2) +logger.fmt_debug("This is a verbose log message: %q", status) +``` + ## Code Standards ### Testing