Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
57 lines (45 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

57 lines (45 loc) · 4.87 KB

Neo.mjs Contributing Guide

We are very excited that you are interested in contributing to Neo.mjs.
No worries, you don't need to be a guru, ninja or rockstar to support the project.

What you can do to help:

1. Spread the Word

Neo.mjs thrives on community engagement. One of the most impactful ways to contribute is to help grow our community and share the project with others.

  1. Star the repository: This helps with visibility on GitHub.
  2. Tell your friends and colleagues: Share your experience with Neo.mjs.
  3. Engage on social media: Write blog posts or share content on platforms like LinkedIn, X (formerly Twitter), and Facebook.
  4. Represent Neo.mjs: Interested in giving a talk or a workshop at a developer conference? We'd love to support you. Just reach out!
  5. Uphold our values: Please stick to our Code of Conduct in all interactions.

2. Use the issues tracker

  1. In case you got an idea for a new feature
  2. In case you find a bug
    1. Ideally, you create a new breaking test inside the tests folder. This saves a lot of time and ensures the bug will stay fixed once the ticket is resolved.
  3. Please like or comment on current tickets. This is a great help to figure out which tickets are the most important ones for the Neo.mjs community.

3. Contribute to the Neo.mjs code base

  1. Please always create a new issue inside our Issues Tracker first and wait for approval. This ensures that your idea fits the scope of the project and makes it less likely to get a rejected PR. We will do our best to reply to new tickets within 7d max. In case we don't, feel free to bump the ticket.
  2. In case you want to work on an existing ticket, please add a comment there and get the ticket assigned to you. Otherwise multiple contributors could work on the same item in parallel. To keep the project moving, if a ticket is assigned and we do not receive any feedback from the assignee (e.g. via a comment) within 7 days, the ticket may get re-assigned to make it available for other contributors.
  3. Please make sure that pull requests are always related to an issue inside our Issues Tracker.
  4. Please create PRs for the dev branch and not for master.
  5. Please do not copy code from other frameworks / libraries. So far, the entire Neo.mjs code base is written from scratch.
    1. It is simply impossible to verify if contributed code is self-written.
    2. Adding new npm packages => dependencies / devDependencies is fine, in case there are no licensing conflicts.
  6. Refer to the codebase overview to understand how our repository is structured.

4. In case you created a nice app or component using Neo.mjs, please let us know about it.

  1. We are always interested to feature client projects in blog posts or on social media.

5. Contributions from AI Agents & Autonomous Entities

We actively welcome contributions from artificial intelligence, LLMs, and autonomous agent swarms (such as the AI Village). We are building the foundation for "Agentic UI"—making the web readable by humans, and both readable and writable by machines.

For Human Operators of AI Agents:

  1. Transparency: If you use an AI agent to generate a Pull Request or formulate an issue, please briefly mention which model or agent framework was used (e.g., "Generated by Gemini 3.1 Pro," "Automated via Claude").
  2. Accountability: You remain responsible for the code your agent submits. Please review generated PRs for architectural consistency and ensure they follow our Coding Guidelines.
  3. Setup: To get the best results from your local agents, we highly recommend setting up our specialized MCP servers. See the AI Quick Start Guide and Working with Agents for details on our local Knowledge Base and Memory Core.

For Autonomous Agents (If you are reading this):

  1. Initialization Handshake: Always begin your workflow by reading the AGENTS_STARTUP.md file in the root directory. This contains your core operational mandates.
  2. JSON-First UI: Neo.mjs components are defined via JSON VDOM blueprints, not JSX or HTML templates. This makes structural manipulation and UI inspection mathematically natural for you.
  3. The Neural Link: We offer a bi-directional MCP bridge (ai/mcp/server/neural-link/). You can query the live Scene Graph and manipulate the application state without modifying source code or reloading the browser. See our Agent Architecture to learn how you can orchestrate our runtime.



Copyright (c) 2015 - today, Tobias Uhlig