docs: some work on CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,149 @@
+# Contributing
+
+First of all, thanks for considering contributing to this project. All contributions are welcome, whether they are bug
+reports, documentation improvements, feature requests, or pull requests.
+
+If you're not sure where to start, take a look at the [hot topics](#hot-topics) section for some ideas on what you could work on.
+
+
+## Getting started
+### Prerequisites
+These are pretty much the only things you need to have installed on your machine to get started with contributing to
+this project:
+- the [Rust](https://www.rust-lang.org/tools/install) toolchain installed on your machine
+- any working version of [Git](https://git-scm.com/downloads)
+
+### Forking the repository and setting up the project
+1. Click on the `Fork` button at the top right corner of the repository page to create a copy of the repository to your
+   GitHub account.
+2. Clone the forked repository to your local machine by running the following command in your terminal:
+   ```shell
+   git clone https://github.com/<your-username>/television.git
+   ```
+3. Navigate to the project directory and set up the upstream remote by running the following commands:
+   ```shell
+   cd television
+   git remote add upstream https://github.com/alexpasmantier/television.git
+   ```
+4. Create a new branch for your feature or bug fix:
+   ```shell
+   git checkout -b <branch-name>
+   ```
+5. Make your changes and commit them to your branch:
+   ```shell
+   git add .
+   git commit -m "Your commit message"
+   ```
+6. Push your changes to your forked repository:
+   ```shell
+   git push origin <branch-name>
+   ```
+7. Create a pull request by navigating to the original repository and clicking on the `New pull request` button.
+
+
+### Building the project
+To build the project in debug mode, run the following command in the project directory:
+```shell
+make build_debug
+```
+
+To build the project in release mode, run the following command in the project directory:
+```shell
+make build_release
+```
+Formatting the code
+```shell
+make format
+```
+Linting the code
+```shell
+make lint
+```
+Running the tests
+```shell
+make test
+```
+
+### Project structure
+The project is laid out in several rust crates that are organized in the following way:
+- `television`: the main binary crate that contains the CLI application
+- `television_channels`: a library crate that contains the channel implementations
+- `television_derive`: a library crate that contains the derive macros used in the project
+- `television_fuzzy`: a library crate that contains the fuzzy matcher
+- `television_previewers`: a library crate that contains the previewer implementations
+- `television_utils`: a library crate that contains utility functions and types used in the project
+
+
+### Contributing a new channel
+Channels are just structs that implement the `OnAir` trait.
+
+As such, channels can virtually be anything that can respond to a user query and return a result under the form of a list of entries. This means channels can be anything from conventional data sources you might want to search through (like files, git repositories, remote filesystems, environment variables etc.) to more exotic implementations that might inclue a REPL, a calculator, a web browser, search through your spotify library, your email, etc.
+
+When contributing a new channel, you should create a new module in the `television_channels` crate with a new struct for
+your channel that implements the `OnAir` trait.
+```rust
+// crates/television_channels/src/channels/my_new_channel.rs
+
+use television_channels::channels::OnAir;
+
+pub struct MyNewChannel;
+
+impl OnAir for MyNewChannel {
+    // Implement the OnAir trait for your channel here
+}
+```
+
+You should also add your channel to the `TelevisionChannel` enum in the `television_channels` crate.
+```rust
+// crates/television_channels/src/channels.rs
+
+#[derive(ToUnitChannel, ToCliChannel, Broadcast)]
+pub enum TelevisionChannel {
+    // Other channels
+    MyNewChannel,
+}
+```
+
+**TODO**: document transitions between channels and previewers
+
+
+## Hot topics
+Here are some ideas for contributions that would be very welcome:
+
+- `Customization`:
+  - allow users to customize more of the UI (UI colors, layouts, etc.)
+  - allow users to customize the behavior of the application (e.g. the default channel, fuzzy matching constants, channel heuristics, etc.)
+- `Channels`:
+  - new channel ideas:
+    - shell history
+    - git (commits, branches, status, diff, ...)
+    - remote filesystems (s3, ...)
+    - kubernetes resources (jobs, pods, deployments, services, ...)
+    - recent directories
+    - makefile commands
+    - etc.
+  - add more tests for existing channels
+- `Previewers`:
+  - new previewer ideas:
+    - previewing text in documents (pdfs, archives, ...)
+    - previewing images (actually already implemented but commented out)
+    - remote files (s3, ...)
+    - etc.
+  - add more tests for existing previewers
+- `Documentation`:
+  - add more technical documentation to the project
+    - general design of the TUI application
+    - design of channels, previewers, transitions, etc.
+    - how to contribute a new channel, previewer, etc.
+  - more docstrings in the code
+- `Performance`:
+  - working on reducing coupling between the different crates in the project
+  - working on reducing the number of allocations and copies in the code
+- `Project`:
+  - polish project configuration:
+    - CI/CD
+    - code formatting
+    - linting
+
+
+

README.md

@@ -35,6 +35,21 @@ By default, `television` will launch with the `files` channel on.
 |:--:|
 | *`tv`'s `files` channel running on the *curl* codebase* |
 
+#### Matcher behavior
+`television` uses a fuzzy matching algorithm to filter the list of entries. The algorithm that is used depends on the
+input pattern that you provide.
+
+| Matcher | Pattern |
+| --- | --- |
+| Fuzzy | `foo` |
+| Substring | `'foo` / `!foo` to negate |
+| Prefix | `^foo` / `!^foo` to negate |
+| Suffix | `foo$` / `!foo$` to negate |
+| Exact | `^foo$` / `!^foo$` to negate |
+
+For more information on the matcher behavior, see the
+[nucleo-matcher](https://docs.rs/nucleo-matcher/latest/nucleo_matcher/pattern/enum.AtomKind.html) documentation.
+
 ## Keybindings
 Default keybindings are as follows:
 
@@ -60,16 +75,18 @@ The following channels are currently available:
 - `Stdin`: search through lines of text from stdin.
 
 
-## Design
+## Design (high-level)
 #### Channels
 **Television**'s design is primarily based on the concept of **Channels**.
+Channels are just structs that implement the `OnAir` trait. 
 
-A **Channel** is a source of data that can be used for fuzzy finding. It can be anything from a file system directory, a git repository, a list of strings, a list of numbers, etc. 
+As such, channels can virtually be anything that can respond to a user query and return a result under the form of a list of entries. This means channels can be anything from conventional data sources you might want to search through (like files, git repositories, remote filesystems, environment variables etc.) to more exotic implementations that might inclue a REPL, a calculator, a web browser, search through your spotify library, your email, etc.
 
-**Television** provides a set of built-in **Channels** that can be used out of the box (see [Built-in Channels](#📺-built-in-channels)). The list of available channels
+
+
+**Television** provides a set of built-in **Channels** that can be used out of the box (see [Built-in Channels](#built-in-channels)). The list of available channels
 will grow over time as new channels are implemented to satisfy different use cases. 
 
-Because a **Channel** is nothing more than a source of data that can respond to a user query, channels can virtually search through anything ranging from a local file system to a remote database, a list of environment variables, something passed through stdin, etc.
 
 #### Transitions
 When it makes sense, **Television** allows for transitions between different channels. For example, you might want to
@@ -219,3 +236,9 @@ enter = "SelectEntry"
 ctrl-s = "ToggleSendToChannel"
 ```
 </details>
+
+## Contributions
+
+Contributions, issues and pull requests are welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.

crates/television_channels/src/lib.rs

@@ -1,17 +1,2 @@
 pub mod channels;
 pub mod entry;
-
-pub fn add(left: u64, right: u64) -> u64 {
-    left + right
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn it_works() {
-        let result = add(2, 2);
-        assert_eq!(result, 4);
-    }
-}