From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: mail-a.sr.ht; dkim=pass header.d=maniero.me header.i=@maniero.me Received: from bisque.elm.relay.mailchannels.net (bisque.elm.relay.mailchannels.net [23.83.212.18]) by mail-a.sr.ht (Postfix) with ESMTPS id 01CF120067 for <~johnnyrichard/olang-devel@lists.sr.ht>; Sat, 17 Feb 2024 04:23:30 +0000 (UTC) X-Sender-Id: hostingeremail|x-authuser|carlos@maniero.me Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 2F249901470 for <~johnnyrichard/olang-devel@lists.sr.ht>; Sat, 17 Feb 2024 04:23:29 +0000 (UTC) Received: from uk-fast-smtpout2.hostinger.io (unknown [127.0.0.6]) (Authenticated sender: hostingeremail) by relay.mailchannels.net (Postfix) with ESMTPA id 2B35F9019B8 for <~johnnyrichard/olang-devel@lists.sr.ht>; Sat, 17 Feb 2024 04:23:28 +0000 (UTC) ARC-Seal: i=1; s=arc-2022; d=mailchannels.net; t=1708143808; a=rsa-sha256; cv=none; b=78TpJ4691/dHkg59LwX4XSca1gYbNV16pY3vMHFDX1sTLikaqtIPQIBN/0uaVzrZ7Dz9Gd jjzFYbUsyoxJ6WQJAEqBdl+0/xK2wMKRYvAFNem8numsOkWXjs6xJrQBUZY8xf0n6/K5Ta ywynVQnc1i02q02cBttq2n1+ACvic8lDc3liD5zTEo5ZXiajOAKW33nnLYmS1H3pC8DXU9 HHwmH2a0dO4Ukxi44mmaOptKhbMKVYW3g4K1wPom5GSIu27T/8yhZxOdfjRr5Hmy+PKAMT carantfTkAzMIW6KIGoljy5kOEDa1O1J2OmrOEECk68W1O9ie2KQ4vC5X+vU3g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=mailchannels.net; s=arc-2022; t=1708143808; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding:dkim-signature; bh=xPxRsRSlAb/LHrx2wogWc1Sk5YWeewDCcmQ0CiM6H2U=; b=peiLmXOxZXAXygj0+sMf++6IfxFR6Z9QLHmWCuRaJfARHC+TnZTmweJnuuXmXLTLceucJw bUhLeHcgBeEZVnINFjlnTllqvE6QLSa8/ieWIhh4fWDprRJ3CSG3ChqK0c9X44B2Zwjx0i ozG2tgRXmWJEXbvGqQTH/OvoBf9+ou0u/b4Z2BhtYHcO4Lvrkju/Yc7cq1wSQCMtWFSRhy 2G2h/os8milAbX8V2oWTIjL6WZgGCdic3DMs6mduAVgqlcJ75VqClS3ANv7+phj/bYmXXj RW+EkxDKl+Dk+9h3Sx0p3YxKBS7OHkVvk9OktYHZbIZn4WiAULlKTkn1oAu1hg== ARC-Authentication-Results: i=1; rspamd-6bdc45795d-9xwmf; auth=pass smtp.auth=hostingeremail smtp.mailfrom=carlos@maniero.me X-Sender-Id: hostingeremail|x-authuser|carlos@maniero.me X-MC-Relay: Neutral X-MailChannels-SenderId: hostingeremail|x-authuser|carlos@maniero.me X-MailChannels-Auth-Id: hostingeremail X-Plucky-Harbor: 18685a9a55211320_1708143808873_1172574347 X-MC-Loop-Signature: 1708143808873:1652746849 X-MC-Ingress-Time: 1708143808872 Received: from uk-fast-smtpout2.hostinger.io (uk-fast-smtpout2.hostinger.io [31.220.23.36]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384) by 100.127.49.120 (trex/6.9.2); Sat, 17 Feb 2024 04:23:28 +0000 From: Carlos Maniero DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=maniero.me; s=hostingermail1; t=1708143806; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=xPxRsRSlAb/LHrx2wogWc1Sk5YWeewDCcmQ0CiM6H2U=; b=Cdr9bl46+eR7kUdGkFhVW6o8Z/ZWPoVqXbnMyUxIRt2/yvGxZF6pi1SMbl9HYwPsnYW0WJ uGGIxTlaw3RvPuEyvMaYsdKbF8aobhEj55ePYHLnMYtM8j6r1k4cLpNeg9+q+nwRZVlQKZ Gi2XpwR1686XWgYlnP2o3gp/5wCPxaHFH8+XtfG/uKvtUgOctyydYVW6He44T1jivCdmYc JnAz+Bq8olvl6LZMqb8pGfZhcWqFHhydDQQmZ/6PfZ6XR9FTbEOYg6aQaVshpCPzehU2HX +Qbw/m59TNywuQJsZwZ37tbF/haxs0ad+WosVLmWo91AGHeobUG8AGwjiTiKiw== To: ~johnnyrichard/olang-devel@lists.sr.ht Cc: Carlos Maniero Subject: [PATCH olang] docs: add HACKING documentation Date: Sat, 17 Feb 2024 01:23:12 -0300 Message-Id: <20240217042312.2601873-1-carlos@maniero.me> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-CM-Envelope: MS4xfHQSAWB/6f+KmzcT7aeDkMwgroKpvmpTfgfBbMbAnJx3FZVkjGFpqk/Yu2KQ2goxVG7cBJ+BZ8Uc7wRJpC7boBdZR8MC5JiozQga6bADSRAo3bx0Dcq9 JTSDWOz6Ecqd/3ews1js+b6tTRrRkf6VcsI1OPe8zTNzzoG5ipC/7TVCuwJGk2mh1Wv0lQaUBPwyY7XPzHexTmfT7MobPJ+YRY0E+AobFJnrMg95+u9/un/D Hiz1BXPx8TG5DKb/8C218Q== X-CM-Analysis: v=2.4 cv=Rp/DLjmK c=1 sm=1 tr=0 ts=65d034bd a=5+VMC1FZ3J4mVPAKpPmAqg==:117 a=5+VMC1FZ3J4mVPAKpPmAqg==:17 a=IkcTkHD0fZMA:10 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=BXDaF_L80NYA:10 a=bwGbKnmsAAAA:8 a=znzk5KmSAAAA:8 a=GeCaE_zqAAAA:8 a=FK4mDtiCAAAA:8 a=anyJmfQTAAAA:8 a=Fze1A0053kVDGMQ-kDgA:9 a=3ZKOabzyN94A:10 a=QEXdDO2ut3YA:10 a=Lcls91HMl2cA:10 a=W2a3rEMdZKgA:10 a=nuVVIWbBudwLbAahYuja:22 a=lVJ2Zv5zgJvBeU6Kyhb9:22 a=nuF4NtFnSiaTm4In9ShQ:22 a=5QsrRA1yHJzePWBNUC-5:22 a=YJ_ntbLOlx1v6PCnmBeL:22 X-AuthUser: carlos@maniero.me X-TUID: yefDi8LZF9yd The purpose of this docs is to teach newcomers developers to start contributing with the project. Signed-off-by: Carlos Maniero --- 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