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