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 seagreen.cherry.relay.mailchannels.net (seagreen.cherry.relay.mailchannels.net [23.83.223.160]) by mail-a.sr.ht (Postfix) with ESMTPS id 93DE8200AC for <~johnnyrichard/olang-devel@lists.sr.ht>; Sat, 17 Feb 2024 18:45:01 +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 1300C4C16D0 for <~johnnyrichard/olang-devel@lists.sr.ht>; Sat, 17 Feb 2024 18:45:00 +0000 (UTC) Received: from fr-int-smtpout5.hostinger.io (unknown [127.0.0.6]) (Authenticated sender: hostingeremail) by relay.mailchannels.net (Postfix) with ESMTPA id 62D954C15A5 for <~johnnyrichard/olang-devel@lists.sr.ht>; Sat, 17 Feb 2024 18:44:59 +0000 (UTC) ARC-Seal: i=1; s=arc-2022; d=mailchannels.net; t=1708195499; a=rsa-sha256; cv=none; b=5T10a0+BjUPIiIZSiMr0s7yi8rokyvVnTnwjcURCuptk9xMaBKBmPiMxlfjQWlTbfNbIZb RcKsQm9UimtgDdT4YHWbSAGeI3oMvPilZGpfnS3q1vOZBiHttdXHHez2FJTCD5Ibc5zfHt K+4BiJP0fIQF7BPVG9TuTklX8chDlZoIgKTySvvzxiOP1Nfm9jJqOHk0KaF0ZV9zza+S/P zeuPdekSvmwjbSJ8XjKqkF/DPzL/r/7bR2R9PMPreVh31QKltIphLwmgQFdzmtfL3zp9BW I9ZeUW+7udx1KqF5XEIrcGuNRgvR1vqaw4/KNM48XzFQvEPrVmcChZepNLFDdQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=mailchannels.net; s=arc-2022; t=1708195499; 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=ct+LJCgxrXL1CXkzo4LhlI3A2I3314wq0xRS0v3uqXk=; b=W7bLkZ0DA12nUYYMTdxR+HzDB2cScI9yfbu78BWeGnjIstDlHl7mWfgEsb5ImVbemIPV51 MzZIXFzQSgku+zY04Vd4OmhnNqPfMJNLzks3aouj5gYP3Ewra2D4XoYnU07psYXXcf+seG tSylc91Un7p7i8kUvxqqCRPO8GFLwr7rcvIJ/IrDKFW1oBtHOrXH0EjG1pmua9NOuT1z3O MmxkgE2uumdKbdXjKjCqa2vXN3jg5hVpYDAkIO7OA/gFnPgEvuNvKkdn5A/rZz6p/gn4GS ZYjqJ4TZw3Es/c9b9h1rhcJRSeHJvpk12rQ7pGUFoq6lmTw78QZwdOLr1FLdvw== ARC-Authentication-Results: i=1; rspamd-55b4bfd7cb-zfkwf; 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-Blushing-Attack: 71c85003673cd93a_1708195499966_132754813 X-MC-Loop-Signature: 1708195499966:2960569481 X-MC-Ingress-Time: 1708195499966 Received: from fr-int-smtpout5.hostinger.io ([UNAVAILABLE]. [89.116.146.168]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384) by 100.108.238.155 (trex/6.9.2); Sat, 17 Feb 2024 18:44:59 +0000 From: Carlos Maniero DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=maniero.me; s=hostingermail1; t=1708195497; 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=ct+LJCgxrXL1CXkzo4LhlI3A2I3314wq0xRS0v3uqXk=; b=J/hyOGHrROA2/MOVQOjptMu/Y7/z302a0y0iXueihvGZ+FnFljmf4ZMAFyvSfhj3zCpkXI hShIXfULtVN1RUIscbDspfYc3ps7yqWjQamWybt3b+7ICHFgilhmPpQTZIVCVlUo8SYIFR PELcl10BDkjpAsWSVnX53y7MmushJLJU2pHOpaW9kk+M5gJGdaLOtg1skDeSJDOGJeHr5G 2RvTEqJphqglXOVr+aFvh+Yep8hmWANLHeeOY3joeMR+mYb3jW48jOmeYhuw+nG4IBWCV/ pS2B94w5DWuXiwS4HgW2V5ixyXxBMfBn7V7qn7ToJwl4EI6ECbfMXYQynPtXFA== To: ~johnnyrichard/olang-devel@lists.sr.ht Cc: Carlos Maniero Subject: [PATCH olang v2] docs: add HACKING documentation Date: Sat, 17 Feb 2024 15:40:26 -0300 Message-Id: <20240217184026.3363538-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: MS4xfLCkx9xtRjipx2ynW4VbPTHyOJMup+DjAwZ3yAkUgypc4Y6GPvm0rrRh4joywkPKgHVl8RVXTFQjqX4LDBUzrqhgLxzhueTVsdVpMbwrMcCBVZGa5ZLj LLj1kkRI6fZfaiEF1pjGsXL9z+dy2Ukj/kmLvY52153u/TzXy/UOPao0mc/NrOBW+DqrA3uUQhpO6MMgiHA0Kq4cdVy0CRdZu5Py8Vd+HEDpXFwdGqujpj8+ wpbjXDSsMn8jJheb7ePBpA== X-CM-Analysis: v=2.4 cv=apu0CzZV c=1 sm=1 tr=0 ts=65d0fea9 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: rL5JPJ5gsvmN The purpose of this docs is to teach newcomers developers to start contributing with the project. Signed-off-by: Carlos Maniero --- v2: replaces the rst with markdown once we are using pandoc now. docs/Makefile | 2 +- docs/pages/hacking.md | 152 +++++++++++++++++++++++++++++++++++++++++- docs/template.html | 3 + 3 files changed, 154 insertions(+), 3 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index e5b7154..059542b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -21,4 +21,4 @@ $(BUILD_DIR): @mkdir -p $@/$(PAGES_DIR) $(BUILD_DIR)/$(PAGES_DIR)/%.html: $(PAGES_DIR)/%.md - $(PANDOC) -s --template template.html -f markdown -t html $< > $@ + $(PANDOC) -s --template template.html -f markdown -t html --toc $< > $@ diff --git a/docs/pages/hacking.md b/docs/pages/hacking.md index 2bb1338..7ebd4b3 100644 --- a/docs/pages/hacking.md +++ b/docs/pages/hacking.md @@ -1,3 +1,151 @@ -% Hacking WIP +% Hacking -WIP +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. + +``` {.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: + +``` {.sh} +make linter +``` + +Most of the common code style mistakes are fixed by: + +``` {.sh} +make linter-fix +``` + +### .editorconfig + +We also provide a **.editorconfig** file at project\'s root. Follow + 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: +. + +To execute tests you can execute: + +``` {.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 +. + +#### Best practices + +1. Write single-purpose commits. +2. Write a meaningful commit message. +3. 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: + +``` {.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-letter** 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: + + +Once you have everything set you just need to send the patch over our +mailing list. + +``` {.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. + +``` {.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! diff --git a/docs/template.html b/docs/template.html index 2a1b721..758b4c4 100644 --- a/docs/template.html +++ b/docs/template.html @@ -58,6 +58,9 @@

$title$

+ + $toc$ + $body$