From 4e45ce1b00f6dc6da2fb4740d468fc1247d0d308 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Mon, 6 Oct 2025 23:53:19 -0500 Subject: [PATCH 1/2] Add summary architecture and contributing guides --- .gitignore | 1 + content/docs/architecture.smd | 88 +++++++++++++++++++++++++++++++++++ content/docs/contributing.smd | 79 +++++++++++++++++++++++++++++++ content/docs/index.smd | 23 ++------- 4 files changed, 171 insertions(+), 20 deletions(-) create mode 100644 content/docs/architecture.smd create mode 100644 content/docs/contributing.smd diff --git a/.gitignore b/.gitignore index 87174b6..1ec4b92 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /public/ +*.bak diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd new file mode 100644 index 0000000..f2d9e0e --- /dev/null +++ b/content/docs/architecture.smd @@ -0,0 +1,88 @@ +--- +.title = "Architecture", +.date = @date("2025-07-06T00:00:00"), +.author = "CJ van den Berg", +.layout = "index.shtml", +.draft = false, +--- + +This document describes in a general way, concepts that help to +understand how the code is organized and where to look at when starting +to contribute developing Flow Control. Make sure you have read +first [help.md](https://github.com/neurocyte/flow/blob/master/help.md) +and use the editor at least in flow mode. We recommend reading the +[deepwiki description](https://deepwiki.com/neurocyte/flow) and join +[Discord](https://discord.com/invite/4wvteUPphx) to ask from the +simplest. + +## Internals + +The foundational unit is the `Buffer` that holds the document in memory; +there might be various opened files, each one loaded in a buffer. +A buffer can be ephemeral, meaning, it is not related to a file, that +might be the product of a `Task` run. Buffers are implementations of +ropes that offer multiple services such as insert characters, load from +file, write to file, load from string, return as string, tell if it has +unsaved changes(dirty), among many others. A buffer can have multiple +`Selections` and `Cursors` interacting with it. The `Buffer Manager` +offers services around the set of buffers. + +A `Project` initially is the directory where flow is opened at, once +opened, it starts processes to discover the files under the directory +hierarchy, interact with lsp and git. When flow is opened, only one +active project is loaded in the current session. The `Project Manager` +offers services around the set of projects. + +## Editor commands and modes + +When a buffer is active, it has an `Editor` attached to it; an editor +might have associated tree-sitter support, given the file type detected, +and offers common services that are aimed to be used by `Commands` to +manipulate the contents of a buffer at a higher level, the selections, +cursors and the `View`. The commands are used by `Modes` with +`Keybindings`. The main mode is Flow and the keybindings can be used +to map to a mode built up entirely on solely calling already created +commands. An example of a mode created by command composition is +`Emacs` mode, for instance, it's possible to create a nano mode with +just keybindings. In the other hand, `Vim` and `Helix` modes have +particular definitions for commands that interact with the buffers, +being modal editors. + +## Text user interface + +`Tui` governs it all offering support for `Palettes` that are known +in other environments as pickers, as well as offering information +through a set of `_views` (i.e. `logview`, `inputview`, +`inspector_view`) and `status` (i.e. `tabs`, `clock`, `branch`, +`linenum`). + +## Operating systems and UI + +libvaxis is in charge of rendering the text and all the interface in +Linux, MacOS, FreeBSD, while in Windows there is an special GUI. + +## Communication between components + +[Thespian](https://github.com/neurocyte/thespian) is in charge of +sending messages between different flow components, for example, +when a widget needs updating information from changing states of +internal data and when components or external processes take +time, for example, tree-sitter queries to highlight the current +file, of a particular language, LSPs, git, running a `shell` +command via a `task`. + +## Programming languages + +There are plenty of programming languages that use tree-sitter via +[flow-syntax](https://github.com/neurocyte/flow-syntax) and whose +language servers and formatters are configured via `file_type_lsp`. +Currently one Language Server is supported for each language. + +## Facilities + +Logging support offers various levels to give feedback for various +actions that ease developing Flow itself and also are used to offer +feedback via `logview`. + + +You can find [contributing guidelines](/docs/contributing). \ No newline at end of file diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd new file mode 100644 index 0000000..3aeacd0 --- /dev/null +++ b/content/docs/contributing.smd @@ -0,0 +1,79 @@ +--- +.title = "Contributing", +.date = @date("2025-07-06T00:00:00"), +.author = "CJ van den Berg", +.layout = "index.shtml", +.draft = false, +--- + + +## Asking for a feature + +Please [open an issue](https://github.com/neurocyte/flow/issues) that +explains what is the requirement, being as descriptive as +possible. First review other issues in case someone already +requested the feature, or join +[Discord](https://discord.com/invite/4wvteUPphx) to ask for +more information. At the end, the issues in github have more +chance to get developed, given that there are plenty of things +to do for this kind of software. + +## Reporting a problem + +If you discover a problem, or unexpected behaviour, feel free to +join [Discord](https://discord.com/invite/4wvteUPphx) to check +if there is a simple way to overcome the inconvenience or to get +some guidance. [Reporting a bug](https://github.com/neurocyte/flow/issues) +is a good way to contribute. When reporting one, it should contain: + +* Flow version. You get it with `flow --version` +* What you were doing, if possible step, by step to reproduce it +* What actually happened +* What was expecting to happen +* Any other information, like screenshots, video, screencast, the +platform allows to add that information. + +Issues later on are tagged with proposed version to solve it, in case it's a +low hanging fruit, it's possible that it can be solved pretty quick. + +Spreading the word is another way to contribute to Flow Code growth. + +## Developing + +[Flow Control](https://flow-control.dev/) is programmed with +[zig](https://ziglang.org/). + +[Fork](https://github.com/neurocyte/flow/fork), no worries, if you +happen to use [codeberg](https://codeberg.org/neurocyte/flow), or +[sourcehot](https://git.sr.ht/~neurocyte/flow), it's possible to +fork and contribute via those services too. + +Discussing via [Discord](https://discord.com/invite/4wvteUPphx) is a good +start to talk about what you are about to offer, or if you decide to pick +an open issue, is a good practice first opening an issue and +commenting in one of the channels to get some feedback and get to +agreements or find guidance. + +This [summary](/docs/architecture) can help on getting started to +follow the codebase. + +### Coding style + +Please follow what you see in the source code for functions, Structs, +variables, const names, etc... Functions have descriptive names to +use less time adding and maintaining comments to communicate the +purpose and intent. + +### Testing + +It's possible that the test set grows as the project evolves, given +that the amount of relationships among components increase the +opportunity to generate regressions. + +## Getting in touch. + + +[Discord](https://discord.com/invite/4wvteUPphx) and +[Github issues](https://github.com/neurocyte/flow/issues) are the +main channels to do so. + diff --git a/content/docs/index.smd b/content/docs/index.smd index b70e339..eb377d3 100644 --- a/content/docs/index.smd +++ b/content/docs/index.smd @@ -4,24 +4,7 @@ .author = "CJ van den Berg", .layout = "index.shtml", .draft = false, ---- +--- -The terminal Editor that came to reallity - -## Features -We have keybindings - -We have modes - -We have syntax highlighting - -We have multiple cursors - -## Differential - -## What we have - -## Friendly Projects -* [Zig](https://ziglang.org/) -* [Zine](https://zine-ssg.io/) -* [Monospace Web](https://owickstrom.github.io/the-monospace-web/) \ No newline at end of file +* [Architecture overview](/docs/architecture) +* [Contributing](/docs/contributing) \ No newline at end of file From 5d6c36a4e3f5a417fede81c1963ae04f6a299f19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Tue, 7 Oct 2025 16:40:03 -0500 Subject: [PATCH 2/2] Added some more links and attribution --- content/docs/architecture.smd | 20 ++++++++++++-------- content/docs/contributing.smd | 17 +++++++++++------ 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/content/docs/architecture.smd b/content/docs/architecture.smd index f2d9e0e..d320069 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture.smd @@ -1,7 +1,7 @@ --- .title = "Architecture", .date = @date("2025-07-06T00:00:00"), -.author = "CJ van den Berg", +.author = "Igor Támara", .layout = "index.shtml", .draft = false, --- @@ -11,9 +11,12 @@ understand how the code is organized and where to look at when starting to contribute developing Flow Control. Make sure you have read first [help.md](https://github.com/neurocyte/flow/blob/master/help.md) and use the editor at least in flow mode. We recommend reading the -[deepwiki description](https://deepwiki.com/neurocyte/flow) and join +[deepwiki description](https://deepwiki.com/neurocyte/flow) for a more +in depth documentation and joining [Discord](https://discord.com/invite/4wvteUPphx) to ask from the -simplest. +simplest. If something does not look accurate on this documentation or +in deepwiki. Do not hesitate to ask in the channels and open a PR to +improve anything. ## Internals @@ -58,8 +61,9 @@ through a set of `_views` (i.e. `logview`, `inputview`, ## Operating systems and UI -libvaxis is in charge of rendering the text and all the interface in -Linux, MacOS, FreeBSD, while in Windows there is an special GUI. +[libvaxis](https://github.com/rockorager/libvaxis) is in charge of +rendering the text and all the interface in Linux, MacOS, FreeBSD, +while in Windows there is an special GUI. ## Communication between components @@ -67,8 +71,8 @@ Linux, MacOS, FreeBSD, while in Windows there is an special GUI. sending messages between different flow components, for example, when a widget needs updating information from changing states of internal data and when components or external processes take -time, for example, tree-sitter queries to highlight the current -file, of a particular language, LSPs, git, running a `shell` +time. For example, tree-sitter queries to highlight the current +file of a particular language, LSPs, git, running a `shell` command via a `task`. ## Programming languages @@ -85,4 +89,4 @@ actions that ease developing Flow itself and also are used to offer feedback via `logview`. -You can find [contributing guidelines](/docs/contributing). \ No newline at end of file +We have some [contribution guidelines](/docs/contributing). \ No newline at end of file diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index 3aeacd0..f7a6c7f 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -1,7 +1,7 @@ --- .title = "Contributing", .date = @date("2025-07-06T00:00:00"), -.author = "CJ van den Berg", +.author = "Igor Támara", .layout = "index.shtml", .draft = false, --- @@ -33,8 +33,9 @@ is a good way to contribute. When reporting one, it should contain: * Any other information, like screenshots, video, screencast, the platform allows to add that information. -Issues later on are tagged with proposed version to solve it, in case it's a -low hanging fruit, it's possible that it can be solved pretty quick. +Issues later on are tagged with proposed version to solve them, in case +it's a low hanging fruit, it's possible that it can be solved pretty +quick. Spreading the word is another way to contribute to Flow Code growth. @@ -45,7 +46,7 @@ Spreading the word is another way to contribute to Flow Code growth. [Fork](https://github.com/neurocyte/flow/fork), no worries, if you happen to use [codeberg](https://codeberg.org/neurocyte/flow), or -[sourcehot](https://git.sr.ht/~neurocyte/flow), it's possible to +[sourcehut](https://git.sr.ht/~neurocyte/flow), it's possible to fork and contribute via those services too. Discussing via [Discord](https://discord.com/invite/4wvteUPphx) is a good @@ -62,7 +63,12 @@ follow the codebase. Please follow what you see in the source code for functions, Structs, variables, const names, etc... Functions have descriptive names to use less time adding and maintaining comments to communicate the -purpose and intent. +purpose and intent. Don't worry about commenting each function, module +or parameter, there are automated tools that are currently helping +with this, take a peek on [deepwiki](https://deepwiki.com/neurocyte/flow), +if you find something inaccurate in those docs or others, do open an +issue or jump in [Discourse to comment](https://discord.com/invite/4wvteUPphx) +and comment. ### Testing @@ -72,7 +78,6 @@ opportunity to generate regressions. ## Getting in touch. - [Discord](https://discord.com/invite/4wvteUPphx) and [Github issues](https://github.com/neurocyte/flow/issues) are the main channels to do so.