Add sections anchors
This commit is contained in:
Igor Támara
parent
6b5bf768f2
commit
edf3a4d51a
GPG key ID:
8EB1E1BB660E3FB9
3 changed files with 102 additions and 31 deletions
|
|
@ -8,8 +8,7 @@
|
|||
.githubedit = "/docs/architecture.smd",
|
||||
}
|
||||
---
|
||||
Head to: [Contribution guidelines](/docs/contributing).
|
||||
b
|
||||
|
||||
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
|
||||
|
|
@ -19,9 +18,11 @@ and use the editor at least in flow mode. We recommend reading the
|
|||
in depth documentation and joining
|
||||
[Discord](https://discord.com/invite/4wvteUPphx) to ask from the
|
||||
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.
|
||||
in deepwiki. Do not hesitate to ask in the channels and
|
||||
[open a PR](https://github.com/neurocyte/flow-website/pulls) to improve
|
||||
anything.
|
||||
|
||||
[]($section.id("internals"))
|
||||
## Internals
|
||||
|
||||
The foundational unit is the `Buffer` that holds the document in memory;
|
||||
|
|
@ -40,6 +41,7 @@ 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.
|
||||
|
||||
[]($section.id("commands"))
|
||||
## Editor commands and modes
|
||||
|
||||
When a buffer is active, it has an `Editor` attached to it; an editor
|
||||
|
|
@ -55,6 +57,7 @@ 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.
|
||||
|
||||
[]($section.id("tui"))
|
||||
## Text user interface
|
||||
|
||||
`Tui` governs it all offering support for `Palettes` that are known
|
||||
|
|
@ -63,12 +66,14 @@ through a set of `_views` (i.e. `logview`, `inputview`,
|
|||
`inspector_view`) and `status` (i.e. `tabs`, `clock`, `branch`,
|
||||
`linenum`).
|
||||
|
||||
[]($section.id("oses"))
|
||||
## Operating systems and UI
|
||||
|
||||
[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.
|
||||
and Android via Termux, while in Windows there is an special GUI.
|
||||
|
||||
[]($section.id("thespian"))
|
||||
## Communication between components
|
||||
|
||||
[Thespian](https://github.com/neurocyte/thespian) is in charge of
|
||||
|
|
@ -83,6 +88,7 @@ perform, integration with git and running a `shell` command via a
|
|||
`task` all are coordinated thanks to the infrastructure that
|
||||
Thespian provides.
|
||||
|
||||
[]($section.id("languages"))
|
||||
## Programming languages support
|
||||
|
||||
There are plenty of programming languages that use tree-sitter via
|
||||
|
|
@ -90,15 +96,50 @@ There are plenty of programming languages that use tree-sitter via
|
|||
language servers and formatters are configured via `file_type_lsp`.
|
||||
Currently one Language Server is supported for each language.
|
||||
|
||||
[]($section.id("facilities"))
|
||||
## Facilities
|
||||
|
||||
The clipboard is used for copy, paste operations and there is also
|
||||
support to use the system clipboard, copying and pasting to/from it.
|
||||
|
||||
[]($section.id("logging"))
|
||||
### Logging support
|
||||
|
||||
Logging support offers various levels to give feedback for several
|
||||
actions that ease developing Flow itself and also are used to offer
|
||||
feedback via `logview`.
|
||||
feedback via `logview`. To view logs use `f11` to toggle the
|
||||
previous messages, or alternatively, open flow with the option
|
||||
`--show-logs`.
|
||||
|
||||
To log something import
|
||||
|
||||
```zig
|
||||
const log = @import("log");
|
||||
```
|
||||
|
||||
Instantiate the logger, replacing prefix with something meaningful to
|
||||
differentiate from other logging messages.
|
||||
|
||||
```zig
|
||||
const logger = log.logger("prefix");
|
||||
defer logger.deinit();
|
||||
```
|
||||
|
||||
Log something
|
||||
|
||||
```zig
|
||||
logger.print("{} unsaved buffer(s) remaining", .{remaining});
|
||||
```
|
||||
|
||||
[]($section.id("show_input"))
|
||||
### View key presses
|
||||
|
||||
There are situations when you press some keys without the expected
|
||||
behavior happening, to review if flow is getting the keys, or your desktop
|
||||
environment or something else are capturing them, you will want to
|
||||
invoke flow with the option `--show-input`.
|
||||
|
||||
[]($section.id("next"))
|
||||
## Next steps
|
||||
|
||||
* [Guidelines for contributions](/docs/contributing)
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@
|
|||
}
|
||||
---
|
||||
|
||||
[]($section.id("request"))
|
||||
## Asking for a feature
|
||||
|
||||
Please [open an issue](https://github.com/neurocyte/flow/issues) that
|
||||
|
|
@ -20,13 +21,14 @@ 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.
|
||||
|
||||
[]($section.id("issues"))
|
||||
## 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:
|
||||
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
|
||||
|
|
@ -41,6 +43,7 @@ quick.
|
|||
|
||||
Spreading the word is another way to contribute to Flow Code growth.
|
||||
|
||||
[]($section.id("developing"))
|
||||
## Developing
|
||||
|
||||
[Flow Control](https://flow-control.dev/) is programmed with
|
||||
|
|
@ -60,6 +63,7 @@ agreements or find guidance.
|
|||
This [summary](/docs/architecture) can help on getting started to
|
||||
follow the codebase.
|
||||
|
||||
[]($section.id("coding_style"))
|
||||
### Coding style
|
||||
|
||||
Please follow what you see in the source code for functions, Structs,
|
||||
|
|
@ -67,30 +71,33 @@ variables, const names, etc... Functions have descriptive names to
|
|||
use less time adding and maintaining comments to communicate the
|
||||
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 this doc or others, do open an
|
||||
issue or jump in [Discord](https://discord.com/invite/4wvteUPphx)
|
||||
and comment, it's valid to
|
||||
[improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd").
|
||||
with this, take a peek on
|
||||
[deepwiki](https://deepwiki.com/neurocyte/flow); if you find something
|
||||
inaccurate in this doc or others, do open an issue or jump to
|
||||
[Discord](https://discord.com/invite/4wvteUPphx) and comment, it's
|
||||
valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd").
|
||||
|
||||
[]($section.id("commits"))
|
||||
### Commit comments
|
||||
|
||||
It's better to use commits for different purposes, even if they look small and
|
||||
there is a temptation to include on the same new code, fixes and refactors. Making
|
||||
concise and self contained commits make review easier and future fixes possible,
|
||||
It's better to use commits for different purposes, even if they look
|
||||
small and there is a temptation to include on the same new code, fixes
|
||||
and refactors. Making concise and self contained commits make review
|
||||
easier and future fixes possible,
|
||||
in case of need.
|
||||
|
||||
Use these prefixes as much as you can, doing so helps when identifying the features
|
||||
and eases the process of letting others know about what's new, fixed and help
|
||||
communicate better when releasing.
|
||||
Use these prefixes as much as you can, doing so helps when identifying
|
||||
the features and eases the process of letting others know about what's
|
||||
new, fixed and help communicate better when releasing.
|
||||
|
||||
* `feat:` when there is a new feature, if specific to a mode, please use
|
||||
`feat: [mode]`.
|
||||
* `refactor`: when reorganizing code, usually when you make something clearer
|
||||
for future readers and commiters.
|
||||
* `feat:` when there is a new feature, if specific to a mode, please
|
||||
use `feat: [mode]`.
|
||||
* `refactor`: when reorganizing code, usually when you make something
|
||||
clearer for future readers and committers.
|
||||
* `fix:` When something changed to a more expected behaviour.
|
||||
* `build`: the commit doesn't change code at all.
|
||||
|
||||
[]($section.id("testing"))
|
||||
### Testing
|
||||
|
||||
It's possible that the test set grows as the project evolves, given
|
||||
|
|
@ -99,6 +106,17 @@ opportunity to generate regressions. If you are new to zig a good
|
|||
place to start to learn about the codebase is
|
||||
[adding some tests](/docs/testing)
|
||||
|
||||
[]($section.id("resources"))
|
||||
## Resources
|
||||
|
||||
* [nerd fonts cheatsheet](https://www.nerdfonts.com/cheat-sheet): When
|
||||
icons are needed, you can look for them.
|
||||
* [logging](/docs/architecture#logging): When developing flow and need
|
||||
to trace some messages.
|
||||
* [showing key-presses](/docs/architecture#show_input): When the keyboard
|
||||
don't seem to work.
|
||||
|
||||
[]($section.id("next"))
|
||||
## Next steps
|
||||
|
||||
* [Join Discord](https://discord.com/invite/4wvteUPphx)
|
||||
|
|
|
|||
|
|
@ -17,12 +17,13 @@ and also an
|
|||
|
||||
To work with tests you will need to:
|
||||
|
||||
* [Clone](https://github.com/neurocyte/flow) the repo
|
||||
* [Clone](https://github.com/neurocyte/flow) the repository
|
||||
* Have [zig installed](https://ziglang.org/download/). Highly recommended to use
|
||||
[anyzig](https://github.com/marler8997/anyzig)
|
||||
|
||||
Flow tests are placed in the directory `test`.
|
||||
|
||||
[]($section.id("running_tests"))
|
||||
## Running the tests
|
||||
|
||||
To run the full set of tests, inside flow, use `F5`, which runs a task that
|
||||
|
|
@ -35,6 +36,7 @@ zig build test
|
|||
it will work if flow was invoked from the project root, which is the same
|
||||
place that you would normally run the tests when on the terminal.
|
||||
|
||||
[]($section.id("running_a_test"))
|
||||
### Run a particular test
|
||||
|
||||
To run an specific test use `Dtest-filter` option with the name of your
|
||||
|
|
@ -44,6 +46,7 @@ test, i.e., for the test called **test_block_name** use:
|
|||
zig build test -Dtest-filter="test_block_name"
|
||||
```
|
||||
|
||||
[]($section.id("first_test"))
|
||||
## Adding tests
|
||||
|
||||
Tests are needed when:
|
||||
|
|
@ -61,9 +64,10 @@ exercises the functionality and makes proof of it behaving as expected.
|
|||
Maintain the logic test as simple as possible. It's possible to add
|
||||
additional functions to make the tests readable and extendable though.
|
||||
|
||||
public functions are stratightforward tested, while there are some
|
||||
public functions are straightforward tested, while there are some
|
||||
conventions for testing private functions.
|
||||
|
||||
[]($section.id("private_functions_testing"))
|
||||
### Testing private functions
|
||||
|
||||
Some internal logic of a module can be tested without the need to be
|
||||
|
|
@ -106,6 +110,7 @@ try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metric
|
|||
In case there is need of a new test file for concern separation, continue
|
||||
to the next section.
|
||||
|
||||
[]($section.id("new_test_file"))
|
||||
## Adding a new test file
|
||||
|
||||
Three steps are required for adding a new test file:
|
||||
|
|
@ -115,6 +120,7 @@ Three steps are required for adding a new test file:
|
|||
1. Optionally, make available a module to the build system
|
||||
for your particular test
|
||||
|
||||
[]($section.id("create_test_file"))
|
||||
### Create the test file
|
||||
|
||||
Place your test file under `test` directory, the name should be prefixed
|
||||
|
|
@ -123,6 +129,7 @@ with `tests_`.
|
|||
For the rest of this section we will use as a sample
|
||||
`tests_project_manager.zig`.
|
||||
|
||||
[]($section.id("linking_tests"))
|
||||
### Include the test file
|
||||
|
||||
Tests files are linked via `test/tests.zig`, import your new test_file
|
||||
|
|
@ -132,6 +139,7 @@ alphabetically as in our sample:
|
|||
pub const project_manager = @import("tests_project_manager.zig");
|
||||
```
|
||||
|
||||
[]($section.id("import_in_build_zig"))
|
||||
### Import required modules when building tests
|
||||
|
||||
In `build.zig` import the required module under `tests.root_module`, for
|
||||
|
|
@ -144,8 +152,10 @@ tests.root_module.addImport("project_manager", project_manager_mod);
|
|||
[Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c)
|
||||
of adding a new test file for project manager.
|
||||
|
||||
[]($section.id("faq"))
|
||||
## FAQ on tests
|
||||
|
||||
[]($section.id("import_editor"))
|
||||
### I need to test something that requires importing the editor ¿What do I do?
|
||||
|
||||
There are two paths from here:
|
||||
|
|
@ -154,15 +164,17 @@ There are two paths from here:
|
|||
1. Extend the tests to automate via external tools
|
||||
|
||||
|
||||
[]($section.id("lower_level"))
|
||||
### Refactor to test lower level functions
|
||||
|
||||
Refactor the functions involved in the functionality to make them
|
||||
not rely directly with editor and other higher level componets, and
|
||||
not rely directly with editor and other higher level components, and
|
||||
test the lower level ones.
|
||||
|
||||
An example of this can be seen in commands
|
||||
|
||||
### Use aditional tools to test a running flow session
|
||||
[]($section.id("end_to_end"))
|
||||
### Use additional tools to test a running flow session
|
||||
|
||||
Use additional tools to invoke the built editor and send keys to
|
||||
it, modify a file and then compare the initial contents of the file
|
||||
|
|
@ -171,7 +183,7 @@ and the resulting contents of your file and the expected ones.
|
|||
If in doubt about how to do something,
|
||||
[please ask](https://discord.com/invite/4wvteUPphx).
|
||||
|
||||
|
||||
[]($section.id("next"))
|
||||
## Next steps
|
||||
|
||||
* [How to contribute](/docs/contributing)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue