Skip to content

Latest commit

 

History

History
110 lines (78 loc) · 8.75 KB

CONTRIBUTING.md

File metadata and controls

110 lines (78 loc) · 8.75 KB

Contributing to SwarmUI

Please open an Issue or Discussion, or ask on Discord before opening a pull request, to make sure your work doesn't overlap with others, and to ensure you don't spend time working on an idea that doesn't make sense or can't be pulled.

Extensions

Want to make something out of scope for Swarm's core systems? Make an extension! See the Making Extensions Doc

If your extension is ready to go, post it in the #extensions channel on Discord, and open a pull request adding it to the file launchtools/extension_list.fds

Pull Requests

Pull Requests (PRs) on GitHub are how you submit changes to the core codebase.

When writing a pull request, you are expected:

  • To follow language-specific format guidelines (see below sections)
  • To fit the style and design of the project
  • To have discussed your PR in advance (GitHub issue, or Discord) before making it
  • To explain your PR when submitting it in the OP (doesn't have to be long, just has to be reasonably clear enough to figure out what's going on)
  • To be able and willing to answer questions regarding your code, or make changes if/when needed.
    • ie, you must actually understand your own work. If an LLM wrote it for you and you don't understand it, do not try to PR it.
  • To have tested your own work prior to submitting.

Pull Requests from newer contributors that are not directly addressing an issue with the Easy PR label may be closed without warning or reason. Frequent contributors may take issues that do not have that label. Only trusted maintainers should make code changes not related to a listed issue.

Pull Requests should seek to solve exactly one problem at a time. Do not combine several different things into one PR, please submit those separately.

Git

If you're new to git, here's some tips:

  • Look up some general guides on how git works to get familiarity with the basic ideas.
    • It's not hard to use at all, but it has a lot of new words to learn, yknow?
  • Use GitHub Desktop, a friendly and clear UI for git management
    • Some wackjobs will tell you to use command line. Absolutely do not. Even if you're pro, CLI is a bad idea for general git management.
  • Always look over the pending changes before committing
  • Always work from a branch, never from master.
  • On the GitHub PR submission page, when you get review comments, look on the Files Changed tab specifically, that properly shows your edits and any comments on it in context, with past comments auto-hidden.

C#

Contributing to the C# server code, or writing an extension? I recommend Visual Studio 2022 as the optimal IDE for this. Follow standard C# formatting rules. Look at existing code if in doubt. We use a modern C# Syntax.

All functions, fields, properties, should have /// XML doc comments.

JavaScript

Contributing to the JS webcode, or writing an extension that uses it? Use any editor of your choice, VS Code is sufficient. Follow mostly the standard JS formatting rules, but look at the existing code. Notable deviations from norm include:

  • always let never const
  • when all else is equal, stick to simpler syntax. For example use == unless === is logically required. Stick to standard for (...) instead of arr.forEach, etc.
  • async block usage is WIP, I want to transition Swarm to use those but there's a lot of callback-based code (sorry I just hadn't realized async was well-supported in browsers now when I started work on Swarm, this one's my fault - mcmonkey)

A lot of JS code was written as a quick in-file dump (I focused a lot more on C# quality than JS quality when the project was young). Work is progressing on moving it over to class-based systems. After it's all class based, I'd like to enable 'use strict' and import. Possibly an upgrade to typescript after that.

All code under the class-based systems should have /** doc comments atop classes and functions.

For the most part, when contributing, simply match the style of the area you're in.

Python

Contributing to the Python code? Use any editor of your choice, VS Code is sufficient. Follow standard python rules, and for any deviations generally follow comfy rules.

Writing an extension with custom python? If it's comfy nodes, consider writing it in a way that allows it to be imported to regular comfy installs too, and write according to comfy standards.

Languages

Want to help translate Swarm into another language?

  • Translations are likely going to be reworked from the ground up soon, maybe hold off on language updates.
  • First: you're going to have to speak English. The English text is the "one true root" language that all other languages are derived from, it would be problematic to translate a translation.
  • Are you just helping improve an existing language?
    • Great! Just edit the file in languages/(language-code).json and improve the translations included
  • Do you want to add a new language?
  • Are you adding new translatable keys?
    • I use the hidden webconsole call debugSubmitTranslatables() to generate languages/en.debug which contains a raw key list, and then use --add-json to add it in with the translate tool.

Themes

Want to add a new theme or change an existing one?

  • First: make sure it's reasonable and relevant to add to the core. If you're doing crazy experimental stuff, maybe it should be an extension.
  • Theme files are in src/wwwroot/css/themes
  • You can add any new theme to the registered theme list in WebServer.cs, PreInit() block.
  • Most core themes should only edit colors, other CSS edits should only be with good well considered reasons.
    • If you must modify non-color CSS, make the minimum possible changes.
    • Non-color CSS should be in a separate file from the color changes, similar to how modern.css is a separate file for major edits.
  • All new themes should use modern.css as the first stylesheet entry. Themes not built atop modern.css will not be accepted to the core.
  • Themes should ideally be added to Install page, but not strictly required.

LLM-Written Code

This is an AI project, so obviously we don't hate AI here. However, we also understand its limitations well, so we ask that you are reasonable about using of AI language models:

  • "Intelligent autocomplete" tools (Copilot, Cursor, etc.) are completely fine.
  • Asking a chatbot for tips or methods to use is fine. Double-check the accuracy of anything it claims before doing it.
  • "Hey ChatGPT write this code for me" or similar, is NEVER okay.
  • Agentic development tools are experimental, only very powerful ones well tuned to the codebase tend to get even close, and even then they require significant experienced human monitoring, and therefore are not permitted for external contribution.
    • If you are able to make numerous contributions on your own and demonstrate capable understanding of the repo, you may request permission to use agents for contributing.
  • Broadly, make your own decisions about what to write and how to write it. The LLM can replace the keyboard clacking, and it can help you recall specific functions, but they tend to be quite bad at larger scale planning.
  • You are expected to understand every line of your own code submission. You may even be asked during PR review.
  • Especially double check that any LLM written code both (1) followed the usual formatting rules and (2) used relevant functions.
    • LLMs will often write to much older standards of the language, and will be unaware that there are 'proper' functions in the local context, eg an LLM writing JS might try to use fetch (JS API) instead of the proper genericRequest (Swarm site.js)
  • You are expected to have tested your own contribution, obviously. If you submit non-functional LLM-written code you may be barred permanently from further contributions, as a spammer.

Legal

By submitting a contribution to this repo, you agree to grant a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to Alex "mcmonkey" Goodwin to use, copy, modify, and distribute your contribution under the terms of the MIT License, view LICENSE.txt for details, and under any future license we may change to.