Skip to main content

Contributing

Contributing to p5.asciify​

With the v0.7.0 release, including a full rewrite of the codebase from JavaScript to TypeScript, p5.asciify is now more accessible than ever for contributions. This document outlines the steps to contribute to the project, including setting up the development environment, running the project locally, and submitting a pull request.

Requirements​

Node.js and NVM​

This project uses Node.js v22.11.0 and requires Node Version Manager (NVM) for version management:

  1. Install NVM: For Windows:

    For macOS/Linux:

  2. Verify NVM installation:

nvm --version
  1. Install and use required Node.js version:
nvm install 22.11.0
nvm use 22.11.0

[!NOTE] The .nvmrc file in the project root specifies the required Node.js version. Simply run nvm use in the project directory to use the correct version.

npm​

This project uses npm for package management. Verify that npm v10.9.0 is installed by running the following command:

npm --version

You can install a specific version of npm using the following command:

npm install -g npm@10.9.0

Setting up the development environment​

To set up the development environment for p5.asciify, follow these steps:

  1. Clone the repository to your local machine using the following command:
git clone https://github.com/humanbydefinition/p5.asciify.git
  1. Navigate to the project directory:
cd p5.asciify
  1. Install the project dependencies:
npm install

With the development environment set up, you can now run the project locally.

Running the project locally​

p5.asciify uses vite for development and bundling. To run the project locally, use the following command:

npm run dev

This command starts a local development server at http://localhost:5173/examples/ where you can view the examples and test the library. The server automatically reloads when you make changes to the source code.

Building the project​

To build the project for production, use the following command:

npm run build

This command generates a production build of the project in the dist directory.

Running tests​

p5.asciify uses vitest for running tests. To run the tests, use the following command:

npm run vitest

This command runs the test suite and outputs the results in the terminal. Currently, most functionality is untested through automated tests, so any contributions to the test suite are highly appreciated.

Running Storybook​

p5.asciify uses storybook for visual testing. To run Storybook, use the following command:

npm run storybook

This command starts a local development server at http://localhost:6006 where you can currently view selected example sketches. The server automatically reloads when you make changes to the source code. Currently, the Storybook setup is minimal, and any contributions to expand it are highly appreciated.

Running the documentation​

p5.asciify uses typedoc for generating documentation from the source code. To build the documentation, use the following command:

npm run build-docs

Alternatively, you can run the documentation server using the following command, which automatically reloads when you make changes to the source code:

npm run dev-docs

typedoc generates the documentation in the docs directory as .md files. As of now, there is definitely room for improvement in some areas, so all contributions to the documentation are welcome! There are also some settings that need to be adjusted to generate a more comprehensive documentation.

Besides the automated documentation, the .md files in ./repo_assets/wiki/ are manually maintained and pasted into the GitHub wiki when changes are made.

Submitting a pull request​

If you identify an issue or have a feature you would like to contribute to p5.asciify, feel free to just create an issue of create a pull request. Within the Issues tab, you can find a list of issues that are open and ready for contributions. If you have an idea for a new feature or improvement, feel free to create a new issue and discuss it with the maintainers.

To submit a pull request, follow these steps:

  1. Fork the repository to your GitHub account.
  2. Create a new branch for your changes.
  3. Make your changes and commit them to your branch.
  4. Push your branch to your fork.
  5. Create a pull request from your branch to the main branch of the p5.asciify repository.

With these steps, you can now contribute to p5.asciify and help improve the library for everyone. If you have any questions or need help with the contribution process, feel free to reach out. Happy coding!