From 1441920f0b41f544e83a5d01a4947fcffa9dceab Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Tue, 17 Mar 2026 14:38:39 +0530 Subject: [PATCH 1/7] Create docs folder and make docs md --- TODO.txt => docs/TODO.md | 0 api.txt => docs/api.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename TODO.txt => docs/TODO.md (100%) rename api.txt => docs/api.md (100%) diff --git a/TODO.txt b/docs/TODO.md similarity index 100% rename from TODO.txt rename to docs/TODO.md diff --git a/api.txt b/docs/api.md similarity index 100% rename from api.txt rename to docs/api.md From 32154e75c35383016d7b30a24f31ed4e75aafba0 Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Tue, 17 Mar 2026 17:46:46 +0530 Subject: [PATCH 2/7] add CONTRIBUTING.md --- docs/{api.md => API.md} | 0 docs/CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) rename docs/{api.md => API.md} (100%) create mode 100644 docs/CONTRIBUTING.md diff --git a/docs/api.md b/docs/API.md similarity index 100% rename from docs/api.md rename to docs/API.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..df9f4c9 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,34 @@ +Hi there! Welcome to L5 contributing! Here are a few things to know: + +The GitHub issues are for bugs and feature requests for the L5 library itself. If you have a general question or bug programming with L5 please post it in the [L5 forum](https://discourse.processing.org/c/l5/) + +Please be sure to review our [principles](https://github.com/L5lua/L5/blob/main/docs/PRINCIPLES.md). These things are very important to us. + +Check out the [contributor docs](https://l5lua.org/contributing/) for more in-depth details about contributing code, bug fixes, and documentation. + +## Contributor Guidelines (key points) + +The following are some key points from our [contributor guidelines](https://l5lua.org/contributing/). Please read the full document for more details. + +### Get Assigned Before Working on an Issue +You should not “jump the queue” by filing a PR for an issue that either someone else has indicated willingness to submit a contribution or has already been assigned to someone else. We will always prioritize the “first assigned, first serve” order for accepting code contributions for an issue. If you file a PR for an issue while someone else is still working on the same issue, your PR will likely be closed. + +### You may follow up on Stalled Issues +If you see that it has been a few weeks since the last activity on an issue with an assigned individual, you can leave a polite comment on the issue asking for progress and if they need help with the implementation. We generally allow for people to work on their contributions at their own pace, as we understand that most people will often be working on a volunteer basis, or it simply takes more time for them to work on the feature. + +### Only Issues Approved for Implementation May Be Worked On +You should not file a pull request (or start working on code changes) without a corresponding issue or before an issue has been approved for implementation, that is because there is no guarantee that the proposal will be accepted. Any pull requests filed before a proposal has been approved will be closed until approval is given to the issue. + + + +### Preparing Pull Requests +A pull request, more formally, is a request to a repo (in this case, the official L5 repo) to pull or merge changes from another repo (in this case, your forked L5 repo) into its commit history. + +## AI Usage Policy +This project does *not* accept fully AI-generated contributions. AI tools may be used assistively only. As a contributor, you should be able to understand and take responsibility for changes you make to the codebase. + +We maintain the same stance on AI usage as p5.js. Please read the [AI Usage Policy](https://github.com/processing/p5.js/blob/main/AI_USAGE_POLICY.md) before proceeding. \ No newline at end of file From 80b9eb8701d2d3882b768a9ba9c03b436245e3fc Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:04:12 +0530 Subject: [PATCH 3/7] add quickstart --- docs/CONTRIBUTING.md | 54 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index df9f4c9..3067c95 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -8,7 +8,7 @@ Check out the [contributor docs](https://l5lua.org/contributing/) for more in-de ## Contributor Guidelines (key points) -The following are some key points from our [contributor guidelines](https://l5lua.org/contributing/). Please read the full document for more details. +The following are some key points to keep in mind when contributing to L5: ### Get Assigned Before Working on an Issue You should not “jump the queue” by filing a PR for an issue that either someone else has indicated willingness to submit a contribution or has already been assigned to someone else. We will always prioritize the “first assigned, first serve” order for accepting code contributions for an issue. If you file a PR for an issue while someone else is still working on the same issue, your PR will likely be closed. @@ -28,6 +28,58 @@ Make sure your code follows the established code standards for L5. Any git commi ### Preparing Pull Requests A pull request, more formally, is a request to a repo (in this case, the official L5 repo) to pull or merge changes from another repo (in this case, your forked L5 repo) into its commit history. +## Quickstart + +If you want to work/contribute to L5 codebase as a developer, you can follow the following steps: + +1. [Create a fork of L5.](https://docs.github.com/en/get-started/quickstart/fork-a-repo) +2. [Clone your created fork to your computer.](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) +3. [Add upstream using the following command](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork): + + ``` + git remote add upstream https://github.com/L5lua/L5 + ``` + +4. Make sure your machine has [Love2D](https://love2d.org/#download) installed; check it with the following command: + + ``` + love --version + ``` + +5. Test everything is working with: + + ``` + love . + ``` + +6. Create a git branch of the `main` branch having a descriptive branch name using: + + ``` + git checkout -b [branch_name] + ``` + +7. As you start making changes to the codebase, it is preferred that you aim to [commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) early and often rather than lump multiple big changes into one commit. A good guideline is to commit whenever you have completed a subtask that can be described in a sentence. + +Here is how you do that: + +- Stage all changes for committing into git with the following command. + +``` +git add . +``` + +- To commit the changes into git, run the following command. + +``` +git commit -m "[your_commit_message]" +``` + +`[your_commit_message]` should be replaced with a relevant commit message that is descriptive of the changes, avoiding generic statements. For example, instead of saying `Documentation fix 1`, say `Add documentation example to circle() function`. + +Repeat the above steps for all commits you will be making while making sure to run `npm test` periodically to make sure things are working. + +8. Once done, you can push the changes and create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). + ## AI Usage Policy This project does *not* accept fully AI-generated contributions. AI tools may be used assistively only. As a contributor, you should be able to understand and take responsibility for changes you make to the codebase. From 7ff28828d10b2c531a959687723a7ea0936d1a33 Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:08:37 +0530 Subject: [PATCH 4/7] add codebase overview and minor fixes --- docs/CONTRIBUTING.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3067c95..6cc095d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,7 +6,7 @@ Please be sure to review our [principles](https://github.com/L5lua/L5/blob/main/ Check out the [contributor docs](https://l5lua.org/contributing/) for more in-depth details about contributing code, bug fixes, and documentation. -## Contributor Guidelines (key points) +## Contributor Guidelines The following are some key points to keep in mind when contributing to L5: @@ -60,8 +60,6 @@ If you want to work/contribute to L5 codebase as a developer, you can follow the 7. As you start making changes to the codebase, it is preferred that you aim to [commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) early and often rather than lump multiple big changes into one commit. A good guideline is to commit whenever you have completed a subtask that can be described in a sentence. -Here is how you do that: - - Stage all changes for committing into git with the following command. ``` @@ -74,11 +72,18 @@ git add . git commit -m "[your_commit_message]" ``` -`[your_commit_message]` should be replaced with a relevant commit message that is descriptive of the changes, avoiding generic statements. For example, instead of saying `Documentation fix 1`, say `Add documentation example to circle() function`. +8. Once done, you can push the changes and create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). -Repeat the above steps for all commits you will be making while making sure to run `npm test` periodically to make sure things are working. +## Codebase overview -8. Once done, you can push the changes and create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). +Some of the key files and folders you will see in the L5 folder are as follows: + +- `L5.lua` - Where all the code for L5 lives +- `main.lua` - This is the main entry point for the L5 library ran by Love2D +- `examples` - This is where you can find example L5 projects +- `docs` - Where the documentation lives + +The other files and folders are either assets or other kinds of support files; in most cases, you shouldn't need to make any modifications. ## AI Usage Policy This project does *not* accept fully AI-generated contributions. AI tools may be used assistively only. As a contributor, you should be able to understand and take responsibility for changes you make to the codebase. From 590c9415bb884d3c52c81db9850197b7d94c98f8 Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:44:20 +0530 Subject: [PATCH 5/7] improve codebase overview in contrib --- docs/CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6cc095d..b4f3b34 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -76,15 +76,61 @@ git commit -m "[your_commit_message]" ## Codebase overview +A little familiarity with Love2D goes a long way in understanding how L5 works. They have a great [wiki](www.love2d.org/wiki/Getting_Started) you can refer to for more details. +L5, overrides some of Love2D's default functions like `love.run()` and `love.draw()` to take control of the rendering loop and state to provide a Processing-style api. + +Almost all internal state is stored inside a `L5_env` table that the library needs such as: + +- current color mode +- whether looping is enabled +- pressed keys +- mouse movement flags +- current font info + +L5 is does its drawing through a back buffer canvas which means: + +- draw onto an offscreen image first +- then draw that image to the screen + +This is a common graphics technique called [**double buffering**](https://en.wikipedia.org/wiki/Double_buffering). + +This library is intentionally “global” and beginner-friendly. This is one of the most important things to understand when reading the codebase. + +In many Lua codebases, you’ll see a style like: + +- `local M = {}` +- `function M.foo() ... end` +- `return M` + +Then users do: + +- `local lib = require("lib")` +- `lib.foo()` + +That is **not** the style here. L5 is more like Processing or p5 global mode: + +- define globals +- provide simple function names +- let the user write very short sketches + Some of the key files and folders you will see in the L5 folder are as follows: -- `L5.lua` - Where all the code for L5 lives -- `main.lua` - This is the main entry point for the L5 library ran by Love2D +- `L5.lua` - The main library that contains all the code for L5 +- `main.lua` - This is the main entry point / runnable sketch used by Love2D - `examples` - This is where you can find example L5 projects -- `docs` - Where the documentation lives +- `docs` - This is where the documentation lives The other files and folders are either assets or other kinds of support files; in most cases, you shouldn't need to make any modifications. +How the code works is that, Love2D is essentially a game engine, it provides the window, input handling, and rendering engine. While `L5.lua` wraps that in a familiar Processing-style api. + +### Running examples + +1. Open one of the files in `L5/examples/` +2. Copy its contents +3. Paste it into the root `L5/main.lua` +4. Run the project with LÖVE using `love .` + ## AI Usage Policy This project does *not* accept fully AI-generated contributions. AI tools may be used assistively only. As a contributor, you should be able to understand and take responsibility for changes you make to the codebase. From 1796eee606c5b53d646467fb2513c3aa615ca883 Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:49:15 +0530 Subject: [PATCH 6/7] remove redundant explanation --- docs/CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b4f3b34..7402bfc 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -122,8 +122,6 @@ Some of the key files and folders you will see in the L5 folder are as follows: The other files and folders are either assets or other kinds of support files; in most cases, you shouldn't need to make any modifications. -How the code works is that, Love2D is essentially a game engine, it provides the window, input handling, and rendering engine. While `L5.lua` wraps that in a familiar Processing-style api. - ### Running examples 1. Open one of the files in `L5/examples/` From c5e5305e5fe9c9caa8c2e99180991a68cb8606b5 Mon Sep 17 00:00:00 2001 From: Nitish C <86357181+Nitish-bot@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:46:03 +0530 Subject: [PATCH 7/7] Credit p5 and make website distinction --- docs/CONTRIBUTING.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7402bfc..aebd891 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,6 +6,8 @@ Please be sure to review our [principles](https://github.com/L5lua/L5/blob/main/ Check out the [contributor docs](https://l5lua.org/contributing/) for more in-depth details about contributing code, bug fixes, and documentation. +If you're looking to contribute to the website, it's code lives in a separate repository at [L5lua/L5-webiste](https://github.com/L5lua/L5-website). This repository is strictly for the core library. + ## Contributor Guidelines The following are some key points to keep in mind when contributing to L5: @@ -132,4 +134,6 @@ The other files and folders are either assets or other kinds of support files; i ## AI Usage Policy This project does *not* accept fully AI-generated contributions. AI tools may be used assistively only. As a contributor, you should be able to understand and take responsibility for changes you make to the codebase. -We maintain the same stance on AI usage as p5.js. Please read the [AI Usage Policy](https://github.com/processing/p5.js/blob/main/AI_USAGE_POLICY.md) before proceeding. \ No newline at end of file +We maintain the same stance on AI usage as p5.js. Please read the [AI Usage Policy](https://github.com/processing/p5.js/blob/main/AI_USAGE_POLICY.md) before proceeding. + +In fact, a large portion of this doc is directly inspired from the [p5.js contributor guidlines](https://github.com/processing/p5.js/blob/main/contributor_docs/contributor_guidelines.md).