[PATCH olang] docs: add HACKING documentation

[PATCH olang] docs: add HACKING documentation

[Carlos Maniero]

The purpose of this docs is to teach newcomers developers to start
contributing with the project.

Signed-off-by: Carlos Maniero <carlos@maniero.me>
---
 docs/index.rst         |   8 ++-
 docs/pages/hacking.rst | 158 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 164 insertions(+), 2 deletions(-)
 create mode 100644 docs/pages/hacking.rst

diff --git a/docs/index.rst b/docs/index.rst
index 4ad0971..f09a97d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,9 +1,13 @@
-Welcome to olang's documentation!
-=================================
+Welcome to olang's docs!
+========================
+The zero programming language.
+
 
 .. toctree::
    :caption: Contents:
 
+   pages/hacking
+
 
 
 Indices and tables
diff --git a/docs/pages/hacking.rst b/docs/pages/hacking.rst
new file mode 100644
index 0000000..5fd7a39
--- /dev/null
+++ b/docs/pages/hacking.rst
@@ -0,0 +1,158 @@
+=======
+Hacking
+=======
+
+We’re thrilled to have you here! Your interest in making olang the most
+exceptional and straightforward language ever is greatly appreciated.
+
+In this document, we’ll outline how you can begin contributing to olang.
+
+First and foremost, clone the project if you haven’t done so already.
+
+.. code-block:: sh
+
+  git clone https://git.sr.ht/~johnnyrichard/olang
+
+Dependencies
+============
+
+The olang compiler is crafted in C. To build the project, you’ll require
+merely three dependencies: **make**, **gcc** (version 11 or higher), and
+**clang-format** (version 14 or higher).
+
+As an optional step, you can install **sphinx** to refresh this documentation.
+
+Code style
+==========
+
+Instead of delineating every element of our coding style, we have adopted the
+use of **clang-format** to enforce the olang code style. Please refer to the
+linter section below for guidance on its application.
+
+Linter
+------
+
+Checking for linter issues:
+
+.. code-block:: sh
+
+  make linter
+
+Most of the common code style mistakes are fixed by:
+
+.. code-block:: sh
+
+  make linter-fix
+
+.editorconfig
+-------------
+
+We also provide a **.editorconfig** file at project's root. Follow
+https://editorconfig.org/ to learn how to make it work with your favorite
+editor.
+
+Testing
+=======
+
+There are two layers of tests **integration** and **unit**. The integration
+test is going to execute the **0c** compiler and check if the generated binary
+acts as expected. Unit tests will test C functions.
+
+For both unit and integration we use **munit** framework: https://nemequ.github.io/munit/.
+
+To execute tests you can execute:
+
+.. code-block:: sh
+
+  make check
+
+
+Submitting a patch
+==================
+
+Before submit a patch, ensure your code follows our coding style and is
+well-tested. After that, you're good to follow the steps bellow.
+
+Step 1: Commit your changes
+---------------------------
+
+Begin by committing your modifications with a detailed and significant commit
+message. We take great pleasure in maintaining a record of our changes over
+time. Skeptical? Execute a **git log** command and admire the well-documented
+history we’ve created so far.
+
+But it isn't all about personal preference. We use a email-driven workflow
+to propose our changes, meaning the commit message you write is the email the
+olang maintainers will get. I won’t go into the perks of the email-driven
+workflow here, but you can check it out at 
+https://drewdevault.com/2018/07/02/Email-driven-git.html.
+
+Best practices
+^^^^^^^^^^^^^^
+
+#. Write single-purpose commits.
+#. Write a meaningful commit message.
+#. Every commit must be production ready.
+  - If the tests or the linter fail, you should not create a fix commit.
+    Instead, you should amend the commit that caused the issue and then resend
+    the patchset.
+
+Step 2: Create your patch
+-------------------------
+
+You can create a patch using the command:
+
+.. code-block:: sh
+  
+  git format-patch --cover-letter -M origin/main -o outgoing/
+
+Step 3: Write a cover letter:
+-----------------------------
+
+The command above generates a **outgoing/0000-cover-letter.patch** file.
+
+ The cover letter is like a pull request description on Github. Replace the
+ \*\*\* SUBJECT HERE \*\*\* with the patchset title and the
+ \*\*\* BLURB HERE \*\*\* with a synopsis of your changes.
+
+If you are sending a single-commit patch you can remove the **--cover-lette**
+argument from **git format-patch** and skip this step.
+
+Step 4: Submit your patch
+-------------------------
+
+Make sure you have configured your **git send-email**. You can learn how to
+configure it here:
+https://git-scm.com/docs/git-send-email#_examples
+
+Once you have everything set you just need to send the patch over our
+mailing list.
+
+.. code-block:: sh
+
+  git send-email outgoing/* --to=~johnnyrichard/olang-devel@lists.sr.ht
+
+The review process
+------------------
+
+Upon submission, you’ll receive an automated email from our pipeline. If the
+check is successful, the olang maintainers will review your patch.
+Subsequently, you’ll receive an email indicating whether your patch has been
+approved, requires changes, or has been rejected.
+
+Submitting changes in a patchset
+--------------------------------
+
+If your patchset requires any modifications, you’ll have to submit a new
+version of your patch. The submission process remains unchanged, except for the
+addition of the version argument to the **git format-patch** command.
+
+.. code-block:: sh
+
+  git format-patch --cover-letter -M origin/main -o outgoing/ -v2
+
+After send a new email with **git send-email**.
+
+----
+
+Thanks again and happy hacking!
-- 
2.34.1

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 19s

[docs: add HACKING documentation][0] from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49586
[1]: mailto:carlos@maniero.me

✗ #1151773 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1151773

Re: [PATCH olang] docs: add HACKING documentation

[Carlos Maniero]

Since we replaced sphinx with pandoc, I sent a new patch with the
hacking document in the markdown format.

Re: [olang/patches/.build.yml] build failed

[Johnny Richard]

My bad... I have made these changes on top of patches not applied on
main branch.

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 29s

[refactor: ast: inline union typedefs][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/54446
[1]: mailto:johnny@johnnyrichard.com

✗ #1302361 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1302361

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 39s

[build: rename linter to format to avoid confusion][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/51175
[1]: mailto:johnny@johnnyrichard.com

✗ #1200225 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1200225

Re: [olang/patches/.build.yml] build failed

[Johnny Richard]

On Thu, Mar 28, 2024 at 02:59:02PM +0000, builds.sr.ht wrote:
> olang/patches/.build.yml: FAILED in 36s
> 
> [fe: lexer: add single line comments support][0] from [Johnny Richard][1]
> 
> [0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50503
> [1]: mailto:johnny@johnnyrichard.com
> 
> ✗ #1181030 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1181030

This build is failing due to a clang bumped version on Arch Linux
repositories.  It was a major bump from 16 to 17 (it has breaking
changes).

We can solve this problem by fixing the version or by bumping our clang
locally.  I will upgrade my clang meanwhile.

Please, consider the patch to fix it.

---->8----
Subject: [PATCH olang] fixup! fe: lexer: add single line comments support


diff --git a/src/pretty_print_ast.c b/src/pretty_print_ast.c
index e950796..129f090 100644
--- a/src/pretty_print_ast.c
+++ b/src/pretty_print_ast.c
@@ -26,7 +26,7 @@
 
 #define ANSI_COLOR_MAGENTA "\x1b[35m"
 #define ANSI_COLOR_RESET "\x1b[0m"
-#define PP_IS_BIT_SET(data, index) ((data)&1 << index)
+#define PP_IS_BIT_SET(data, index) ((data) & 1 << index)
 
 typedef struct pretty_print_node
 {

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 36s

[fe: lexer: add single line comments support][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50503
[1]: mailto:johnny@johnnyrichard.com

✗ #1181030 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1181030

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 35s

[docs: variables specification][0] from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50474
[1]: mailto:carlos@maniero.me

✗ #1179573 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1179573

Re: [olang/patches/.build.yml] build failed

[Carlos Maniero]

oops!

s/see/be

Re: [olang/patches/.build.yml] build failed

[Carlos Maniero]

The failed pipeline seems to see a sourcehut issue.

Tested locally and all fine.

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 40s

[Introduce CLI option for improved AST tree visualization][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50448
[1]: mailto:johnny@johnnyrichard.com

✗ #1178386 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1178386

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 31s

[refactor: rename zero programming language to olang][0] v3 from [Fabio Maciel][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50187
[1]: mailto:fabio@fabiomaciel.com

✗ #1167852 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1167852

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 30s

[parser: abort when parser identifies a syntax error][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50088
[1]: mailto:johnny@johnnyrichard.com

✗ #1164684 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1164684

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 12s

[implement assembly linux x86_64 compiler][0] v2 from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49994
[1]: mailto:johnny@johnnyrichard.com

✗ #1162085 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1162085

Re: [olang/patches/.build.yml] build failed

[Carlos Maniero]

The checks passed just fine in my environment too.

Re: [olang/patches/.build.yml] build failed

[Johnny Richard]

On Mon, Mar 04, 2024 at 06:33:31PM +0000, builds.sr.ht wrote:
> olang/patches/.build.yml: FAILED in 12s
> 
> [implement assembly linux x86_64 compiler][0] from [Johnny Richard][1]
> 
> [0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49981
> [1]: mailto:johnny@johnnyrichard.com
> 
> ✗ #1161742 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1161742

I not sure what is happening, the build works find on my machine.  Looks
like the CI machines are failing to setup the environment, nothing to do
with my changes I believe:

    [#1161745] 2024/03/04 18:36:41 Booting image archlinux (default) on port 22563
    [#1161745] 2024/03/04 18:36:42 Waiting for guest to settle
    [#1161745] 2024/03/04 18:36:49 Sending tasks
    [#1161745] 2024/03/04 18:36:52 Sending build environment
    [#1161745] 2024/03/04 18:36:53 Installing packages
    Warning: Permanently added '[localhost]:22563' (ED25519) to the list of known hosts.
    :: Synchronizing package databases...
     core downloading...
     extra downloading...
     multilib downloading...
    warning: archlinux-keyring-20240208-1 is up to date -- skipping
     there is nothing to do
    Warning: Permanently added '[localhost]:22563' (ED25519) to the list of known hosts.
    error: missing dependency 'initramfs' for package 'linux'
    linux: ignoring package upgrade (6.7.6.arch1-1 => 6.7.8.arch1-1)
    mkinitcpio: ignoring package upgrade (37.3-1 => 38-3)
    Resolving dependencies...
    Checking package conflicts...
    :: uninstalling package 'mkinitcpio-37.3-1' due to conflict with 'cryptsetup-2.7.0-3'
    [#1161745] 2024/03/04 18:36:54 Processing post-failed triggers...
    [#1161745] 2024/03/04 18:36:54 Sending webhook...
    [#1161745] 2024/03/04 18:36:54 Webhook response: 200
    [#1161745] 2024/03/04 18:36:54 Thanks!
    [#1161745] 2024/03/04 18:36:54 Build failed.
    [#1161745] 2024/03/04 18:36:54 The build environment will be kept alive for 10 minutes.
    [#1161745] 2024/03/04 18:36:54 To log in with SSH and examine it, use the following command:
    [#1161745] 2024/03/04 18:36:54
    [#1161745] 2024/03/04 18:36:54 	ssh -t builds@fra02.builds.sr.ht connect 1161745
    [#1161745] 2024/03/04 18:36:54
    [#1161745] 2024/03/04 18:36:54 After logging in, the deadline is increased to your remaining build time.

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 12s

[implement assembly linux x86_64 compiler][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49981
[1]: mailto:johnny@johnnyrichard.com

✗ #1161742 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1161742

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 36s

[string_view: fix stack buffer overflow on to_u32][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49949
[1]: mailto:johnny@johnnyrichard.com

✗ #1160713 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1160713

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 40s

[string_view: add n + 1 test to string_view_to_u32 function][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49946
[1]: mailto:johnny@johnnyrichard.com

✗ #1160663 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1160663

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 36s

[utils: add arena][0] v2 from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49708
[1]: mailto:carlos@maniero.me

✗ #1154158 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1154158

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 36s

[utils: add arena][0] from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49707
[1]: mailto:carlos@maniero.me

✗ #1154146 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1154146

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 42s

[Create --dump-tokens on compiler cli][0] v4 from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49682
[1]: mailto:johnny@johnnyrichard.com

✗ #1153624 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1153624

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 34s

[Create --dump-tokens on compiler cli][0] v2 from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49641
[1]: mailto:johnny@johnnyrichard.com

✗ #1153051 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1153051

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 31s

[Create --dump-tokens on compiler cli][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49640
[1]: mailto:johnny@johnnyrichard.com

✗ #1153048 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1153048

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 18s

[remove sphinx dependency][0] from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49598
[1]: mailto:carlos@maniero.me

✗ #1151949 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1151949

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 15s

[Add integration tests][0] v2 from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49556
[1]: mailto:carlos@maniero.me

✗ #1151085 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1151085

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 16s

[style: fix clang-format format indentation][0] from [Carlos Maniero][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49522
[1]: mailto:carlos@maniero.me

✗ #1150343 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1150343

[olang/patches/.build.yml] build failed

[builds.sr.ht]

olang/patches/.build.yml: FAILED in 13s

[build: enable continuous integration through .build.yml][0] from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/49459
[1]: mailto:johnny@johnnyrichard.com

✗ #1149170 FAILED olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1149170