eessppeelllloo/processing4
1
0
Fork 0
mirror of https://github.com/processing/processing4.git synced 2026-06-16 04:26:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Broad rewrite for the release of the new library template. Improved clarity and tone.

Raphaël de Courville
2025-01-08 17:04:38 +01:00
parent efbfb2c86a
commit 0c545d34d1
1 changed files with 60 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Library-Guidelines.md
+60 -21
@@ -1,32 +1,59 @@
To develop a library for Processing, the [Library Template](https://github.com/processing/processing-library-template) project provides a starting point.
> [!TIP]
> To develop a library for Processing, the [Library Template](https://github.com/processing/processing-library-template) is a great starting point. It simplifies the setup process and helps you avoid many common pitfalls.
>
> For detailed instructions, visit the [template's documentation](https://processing.github.io/processing-library-template/).
>
> Once you're ready to publish your library, submit it through the [GitHub issue form for new contributions](https://github.com/processing/processing-contributions/issues/new?assignees=&labels=new-contribution&projects=&template=new-contribution.yaml).
Please inform us about the existence of your library by posting your contribution in the Processing Forum under [Libraries](https://discourse.processing.org/c/processing/processing-libraries/19). Be sure to let us know where we can find the library's web page online.
## Requirements
Each library contribution should include the following:
* **Documentation** – We recommend using Javadoc-style comments in your library code since it is the most common way to document a Java API. You can use the [Javadoc](https://en.wikipedia.org/wiki/Javadoc) tool or any number of other tools that can convert code with Javadoc-style comments into lovely reference materials. The documentation should be stored in a folder named `reference`, and include an `index.html` file that is the starting point.
* **Examples** – People learn best from examples, so we encourage you to include code examples in your library release. Provide short, well-commented examples to illustrate basic functionality, and include demos to help users understand the potential of your library.
* **Examples** – Users tend to learn best from examples, therefore examples are important for a library release. It is highly recommended to support your library with various sample programs to demonstrate the use and potential of the library.
* **Properties File** – To show information about your library in the PDE's Contribution Manager, you need to provide a `library.properties` file. This file contains the full name of your library, a brief summary of its purpose, and other information. For more details, please read the [[Library Basics|Library-Basics#wiki-DescribingYourLibrary]] page.
* **Properties File** – To show information about your library from within the PDE, you need to provide a `library.properties file. This file contains the full name of your library, a brief summary of its purpose, and other information. More information on the [[Library Basics|Library-Basics#wiki-DescribingYourLibrary]] page.
* **Home Page** – A Processing library should have its own web page, stored at a stable URL (or at least as stable as possible). We recommend using GitHub Pages and the official [Library Template](https://github.com/processing/processing-library-template). The template includes a basic [MkDocs](https://squidfunk.github.io/mkdocs-material/) setup and a script to deploy it automatically to GitHub Pages. Your library's home page should include:
* **Home Page** – A Processing library should have its own web page, stored at a stable URL (or at least as stable as possible), and should include:
- A brief abstract describing the purpose of your library.
- A list of examples showcasing the library’s functionality.
- Some tutorials that demonstrate potential use cases (optional).
- A list of systems (macOS, Windows, Linux) and versions on which the library was successfully tested.
- The latest Processing version the library has been tested with (e.g., Processing 4.3).
- Dependencies, if any (e.g., other libraries or frameworks required by your library).
- Keywords that describe the library’s purpose and features.
- The date of the latest update.
- A link to a `.zip` file containing the library, documentation, and examples.
1. A short abstract that describes the purpose of the library.
2. The library has been successfully tested on which platforms? (OS X, Windows XP and Vista, Linux)
3. The latest Processing version the library has been tested with?
4. Dependencies. Does the library depend on any other library?
5. A list of examples that demonstrate the use and potential of the library.
6. Source code (if open source). We recommend using Google Code to host the source code of a library in a SVN repository, then it is very easy to browse the code online.
7. Keywords that describe the aim and function of the library.
8. Last update. When was the last update of the library?
9. A link to a zip file that includes the library, documentation and examples.
* **Documentation** – We recommend using [Javadoc-style comments](https://en.wikipedia.org/wiki/Javadoc) in your library code since it is the most common way to document a Java API. You can use the [Deploy - Publish Javadoc](https://github.com/marketplace/actions/deploy-publish-javadoc) GitHub action or any number of other tools that can convert code with Javadoc-style comments into a practical reference. The documentation should be stored in a folder named `reference`, and include an `index.html` file that is the starting point. The reference should be updated with each new release.
* **Source Code** – We strongly encourage (and will soon require as a stipulation for placement on the site) that the source to your library be included. If you don't want to distribute source, that's perfectly fine, however only libraries that include their code will be promoted at [processing.org/reference/libraries](http://processing.org/reference/libraries). We're giving away all our stuff, and we want others to do so as well because it's good for the community. This also ensures that your library lives on past your own interest in its maintenance.
* **Source Code** – We strongly encourage including the source code in your library releases (if you’re using GitHub, this is the default). Only libraries with source code will be featured on [processing.org/reference/libraries](http://processing.org/reference/libraries). Sharing your source code helps the community grow and ensures that your library can continue to live on even if you’re no longer maintaining it yourself.
* **License** – Include a license file in your library distribution to specify how your library can be used and shared. For example, [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html). For an overview of some popular open-source licenses, see https://choosealicense.com/licenses/
## Library Naming Rules
> [!WARNING]
> Do not use "Processing" as a prefix in the name of your library.
However, if your library is a Processing port of or a bridge to another framework, you can use a name like “XXX for Processing.”
For example:
- ❌ ~"Processing Box2D"~ is not allowed.
- ✅ "Box2D for Processing" is acceptable.
Additionally, classes should not be prefixed with `P` the way that the core Processing classes are (`PImage`, `PGraphics`, etc). We'd like to reserve that naming for “official” things that are inside `processing.core` and other associated classes.
Same goes for using `Processing`, `Pro`, or `P5`, whether it's a prefix or a suffix.
Similarly, please don't use `processing` as the prefix for your library packages. We need to keep that name space clear for official things as well.
## Folder Structure
> [!NOTE]
> If you use the official [Library Template](https://github.com/processing/processing-library-template), this folder structure is already set up for you. If you’re building your library from scratch, please follow the guidelines below.
Libraries should be distributed as zipped files, and the distribution should be laid out as follows:
* `theLibrary/library/theLibrary.jar`
@@ -42,12 +69,24 @@ Following the folder structure is important because it simplifies documentation,
### Avoid `.DS_Store` files on macOS
Be sure to remove `.DS_Store` files created by macOS from the folders before posting. The following command can be executed in `Terminal.app` to delete all `.DS_Store` files (recursively) from a folder:
Be sure to remove `.DS_Store` files created by macOS before posting your library. These files are unnecessary and can clutter your distribution.
find YourFolderName -name .DS_Store -delete
To prevent `.DS_Store` files from being included in your repository, add the following line to your `.gitignore` file:
Be careful to specify your folder name properly. Don't use `/` or something that would cause the very powerful, very efficient `find` command to remove all `.DS_Store` files from your disk.
```
.DS_Store
```
Or create directly a `.zip` file without `.DS_Store` files:
You can also remove existing `.DS_Store` files from your folders using the `Terminal.app` with the following command:
zip -r theLibrary.zip theLibrary -x "*.DS_Store"
```
find YourFolderName -name .DS_Store -delete
```
Make sure to specify your folder name correctly. Avoid using `/` or anything that might delete `.DS_Store` files across your entire disk.
Alternatively, you can create a `.zip` file without `.DS_Store` files by running:
```
zip -r theLibrary.zip theLibrary -x "*.DS_Store"
```