Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
143 lines (105 loc) · 4.27 KB

CONTRIBUTING.md

File metadata and controls

143 lines (105 loc) · 4.27 KB
Raw

Contributing to formseal-embed

Thanks for your interest in contributing! Contributions of all kinds are welcome — bug fixes, security, new features, docs, and more.

Table of contents

Getting started

  1. Fork the repository and clone your fork:

    git clone https://github.com/useFormseal/embed.git
cd formseal-embed

  2. Install in development mode using pipx (recommended) or pip:

    pipx install -e .

  3. Verify it works:

    fse

Note: Always use pipx install -e . for local dev — it gives you an isolated environment and the version header will display correctly from source.

Project structure

formseal-embed/
├── fse/
│   ├── cli.py                 # Entry point, dispatch
│   ├── __main__.py            # python -m fse support
│   ├── src/                   # Client-side JavaScript (scaffold source)
│   ├── commands/              # CLI commands
│   │   ├── init.py            # fse init
│   │   ├── reset.py           # fse reset
│   │   ├── set.py             # fse set endpoint / key / origin
│   │   ├── field.py           # fse field add / remove
│   │   ├── keygen.py          # fse keygen
│   │   ├── about.py           # fse (no args)
│   │   ├── version.py         # fse --version
│   │   ├── help.py            # fse --help
│   │   └── status.py          # fse status
│   ├── helpers/               # Shared logic
│   │   ├── config.py          # Paths, patching, validation
│   │   ├── errors.py          # Error handlers
│   │   ├── aliases.py         # Shorthand aliases
│   │   └── fields.py          # Field type definitions
│   └── ui/                    # Terminal output helpers
│       ├── styles.py          # Colors, icons
│       ├── headers.py         # header(), rule()
│       └── bodies.py          # br(), row(), ok(), fail(), etc
├── docs/                      # End-user documentation
├── .github/workflows/        # GitHub Actions
├── pyproject.toml
└── version.txt               # Source of truth for the version string

Versioning

The version string lives in version.txt and is the single source of truth. The publish workflow reads it and injects it into the code at build time.

Do not edit the version field in pyproject.toml manually — it gets overwritten by the workflow.

Code style

  • Add a comment at the top of each logical block explaining what it does
  • Follow the patterns already in the file you're editing
  • Use the fse.ui module helpers (info, fail, warn, br, header) for all terminal output
  • Validate before writing — never persist invalid state
  • Never expose secrets or keys in output

Submitting changes

  1. Create a branch off main:

    git checkout -b feat/my-feature

  2. Make your changes and test locally (see Testing)

  3. Commit with clear, descriptive messages

  4. Push and open a pull request against main

Testing

Test the relevant commands manually before opening a PR:

fse                          # check about displays correctly
fse init                     # scaffold a project
fse set endpoint             # interactive endpoint config
fse set key                  # interactive key config
fse status                   # show current config
fse field add email type:email  # add a field

If your change touches the install/packaging path, test with local install method:

pipx install -e .            # local dev

Reporting issues

Report bugs via GitHub Issues.

Please include:

  • Steps to reproduce
  • Expected vs actual behavior
  • Your OS and Python version

Security

If you find a security vulnerability, please report it privately via GitHub Security Advisories.

Do NOT open a public issue for security vulnerabilities.