Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
588 lines (466 loc) · 16.8 KB

CONTRIBUTING.md

File metadata and controls

588 lines (466 loc) · 16.8 KB

FROG logo

🐸 Contributing to FROG

Contribution guidelines for the FROG specification repository
FROG — Free Open Graphical Language

Contents

1. Project Status

FROG is an open specification project defining a modern graphical dataflow language and its related architectural layers.

The repository is still in an active design, cleanup, and stabilization phase. Many documents are already substantial, but some areas are still being clarified, split, aligned, or structurally refactored. Contributions in the form of ideas, corrections, issue reports, specification proposals, architectural cleanup, and wording improvements are welcome.

Because this is a specification repository rather than an ordinary application repository, contributions SHOULD prioritize:

  • clarity,
  • precision,
  • architectural coherence,
  • durable wording,
  • implementable semantics.
This repository is not primarily:
- an app codebase
- a demo collection
- a vendor product manual

This repository is primarily:
- a language specification
- an architecture baseline
- a durable normative document set

2. How You Can Contribute

There are several useful ways to contribute to FROG:

  • improve documentation,
  • clarify ambiguous or inconsistent specification wording,
  • propose architectural refinements,
  • propose new specifications or missing specification areas,
  • identify duplication or ownership conflicts between documents,
  • open issues to discuss design questions,
  • submit pull requests,
  • participate in repository-level architectural discussions.

Early contributions are especially valuable when they improve:

  • cross-document consistency,
  • terminology alignment,
  • ownership clarity between specification layers,
  • normative wording quality,
  • long-term navigability of the repository.

Useful contributions are not limited to adding new text. A contribution may also be valuable when it:

  • removes ambiguity,
  • makes an ownership boundary explicit,
  • turns a duplicated document into a redirect or transition stub,
  • realigns a document with the actual repository architecture,
  • identifies follow-up documents that also need adjustment.

3. Repository Architecture

FROG is organized by architectural responsibility. Contributors SHOULD understand which layer owns which topic before proposing a change. 

FROG/
│
├── Expression/   canonical source specification
├── Language/     normative execution semantics
├── Libraries/    intrinsic standard primitive-library specifications
├── Profiles/     optional standardized capability-family specifications
├── IDE/          authoring, observability, debugging, probes, watch, snippets
│
├── GOVERNANCE.md
├── CLA.md
├── CONTRIBUTING.md
├── LICENSE
└── Readme.md

Layer ownership in summary:

  • Expression/ — canonical source representation and source-visible program objects,
  • Language/ — normative execution semantics and cross-cutting semantic rules,
  • Libraries/ — intrinsic standardized primitive identities, ports, required metadata, and primitive-level definitions,
  • Profiles/ — optional standardized capability families that extend the usable surface of FROG without becoming part of the intrinsic core,
  • IDE/ — authoring architecture, observability, debugging, probes, watch, and snippet workflows.

If a contribution crosses multiple layers, the contributor SHOULD identify which document is the primary owner of the topic. If the current repository state is still transitional, the contributor SHOULD distinguish clearly between:

  • the current published repository state,
  • the proposed architectural direction.
Ownership rule of thumb

How is it written in source?         -> Expression/
What does it mean when it executes?  -> Language/
What does this intrinsic primitive do? -> Libraries/
What does this optional capability do? -> Profiles/
How does the IDE expose or author it?  -> IDE/

4. Where to Start

Before contributing, you SHOULD begin by reading:

  • Readme.md at the repository root,
  • the Readme.md of the relevant top-level directory,
  • the exact file you intend to modify,
  • directly related specification files in the same semantic area,
  • existing issues and discussions when relevant.

Typical entry points:

  • Expression/ — canonical source specification
  • Language/ — normative execution semantics
  • Libraries/ — intrinsic standard primitive-library specifications
  • Profiles/ — optional standardized capability-family specifications
  • IDE/ — IDE architecture, authoring workflows, observability, debugging, and snippets

Contributors SHOULD avoid modifying a document in isolation when its topic is semantically connected to neighboring documents. 

Minimum reading path before a meaningful change

root Readme.md
      ->
relevant layer Readme.md
      ->
target file
      ->
directly related files

5. Recommended Workflow

The preferred contribution workflow follows the standard GitHub model using forks and pull requests. 

Contributor
     │
     │ Fork
     ▼
Your Fork Repository
     │
     │ Create branch
     │ Commit changes
     ▼
Pull Request
     │
     │ Review by maintainers
     ▼
Graiphic / FROG main repository

This workflow allows maintainers to review contributions while preserving repository-wide architectural coherence.

Recommended step-by-step process:

  1. Fork the repository.
  2. Create a branch for your change.
  3. Re-read the current version of the target document and its directly related documents.
  4. Identify whether the target document is the primary owner of the topic.
  5. Identify whether the topic belongs to the intrinsic core, to an optional profile, or to an implementation-facing concern.
  6. Commit your modifications.
  7. Open a Pull Request.
  8. Explain any cross-document conflict, ownership issue, or follow-up cleanup that remains relevant.
  9. Discuss the proposal with maintainers if clarification is needed.

For larger semantic or architectural changes, opening an issue first is RECOMMENDED. 

Recommended large-change flow

issue / discussion
      ->
scope clarification
      ->
document proposal
      ->
pull request

6. Before You Modify a Document

Because FROG is a specification repository, contributors MUST work from the current repository state rather than from memory, assumption, or older draft wording.

Before modifying a document, you SHOULD:

  • start from the current version of the target file,
  • read the repository root Readme.md,
  • read the relevant top-level Readme.md,
  • read directly related files in the same semantic area,
  • identify whether the target document is the primary owner of the topic,
  • identify any cross-document conflict before rewriting,
  • preserve the distinction between current published state and proposed architectural direction when that distinction matters.

Contributors SHOULD NOT:

  • rewrite a document from scratch without taking the current content into account,
  • invent repository structure, file names, or ownership assumptions that are not present in the repository,
  • move semantic ownership casually from one layer to another without clearly explaining the architectural reason,
  • treat an optional profile capability as if it were automatically part of the intrinsic core,
  • remove useful existing content merely because a shorter formulation is possible.
Do not work like this

memory
   ->
assumption
   ->
isolated rewrite

Work like this instead

current repo state
   ->
related documents
   ->
ownership check
   ->
proposed change

7. Contribution Expectations

FROG documents are specification documents. Contributions SHOULD therefore aim for wording that is:

  • explicit,
  • stable over time,
  • architecturally coherent,
  • implementable,
  • clear about ownership and scope.

Contributors SHOULD:

  • preserve useful existing content when possible,
  • prefer conservative rewrites when editing an existing specification,
  • improve the document rather than merely shorten it,
  • distinguish clearly between current published state and proposed architectural direction when that distinction matters,
  • use explicit normative wording when the document is intended to be normative.

Contributors SHOULD call out:

  • ownership conflicts,
  • duplication between documents,
  • ambiguous terminology,
  • under-specified behavior,
  • outdated references or obsolete repository assumptions.

Where it materially improves clarity, contributors SHOULD add:

  • small ASCII diagrams,
  • local tree views,
  • compact ownership summaries,
  • clear transition notes for legacy documents.
Good specification contributions improve:

- wording
- ownership clarity
- cross-document coherence
- future implementability
- repository readability

8. Change Categories

When proposing a change, contributors SHOULD make clear which category the change belongs to:

  • clarification — wording becomes clearer without changing intended semantics,
  • editorial cleanup — formatting, cross-references, navigation, or readability improve without changing intended meaning,
  • additive change — new capability or new specification area is added without invalidating current compliant content,
  • architectural refactor — ownership, layering, or document boundaries are reorganized for coherence,
  • breaking change — previously valid content, assumptions, or interpretations may no longer remain valid.

Major semantic or architectural changes SHOULD explain:

  • what problem they solve,
  • which neighboring documents are affected,
  • whether the change affects the core language, an intrinsic library, an optional profile, or only an IDE-facing concern,
  • whether migration or follow-up cleanup is required.
Change classification matters

small wording fix
   !=
cross-layer semantic refactor

9. Cross-Document Coherence

A contribution is stronger when it respects repository-wide coherence rather than improving one file locally while creating inconsistency elsewhere.

Contributors SHOULD therefore cross-check:

  • top-level ownership boundaries,
  • terminology consistency,
  • duplicate topic coverage,
  • references between layers,
  • examples that may have become stale after an architectural change.

Contributors SHOULD be especially careful when a topic could be mistaken for belonging to the wrong layer. For example:

  • source representation belongs to Expression/,
  • cross-cutting execution meaning belongs to Language/,
  • intrinsic primitive vocabularies belong to Libraries/,
  • optional standardized environment-dependent capability families belong to Profiles/,
  • authoring, observability, debugging, and inspection belong to IDE/.

If a contributor identifies a conflict but only proposes a local change, the Pull Request SHOULD still explain the broader conflict. 

Local improvement is good.
Local improvement that creates a neighboring contradiction is not.

Always ask:
- what else does this change touch?
- which document owns this topic?
- which document may now be stale?

10. Pull Request Expectations

A strong Pull Request SHOULD make review easier rather than forcing maintainers to reconstruct the architectural impact from the diff alone.

A Pull Request description SHOULD therefore identify:

  • the primary target document,
  • the type of change,
  • the ownership boundary involved,
  • the directly related documents that were checked,
  • any known follow-up cleanup that remains outside the current PR.

For semantic or architectural changes, the Pull Request SHOULD also explain:

  • the problem being solved,
  • why the chosen document is the correct owner,
  • whether the change is clarifying existing intent or changing intended behavior,
  • whether any migration or transition note is needed.
Recommended PR summary shape

- change type
- primary owner document
- directly related documents reviewed
- main architectural rationale
- follow-up documents if any

11. Governance

FROG is an open specification project with repository-level governance. Contributors SHOULD remain consistent with the governance model and the current architectural direction of the specification.

See:

GOVERNANCE.md

12. Contributor License Agreement

By submitting a contribution, you agree to the Contributor License Agreement.

See:

CLA.md

If CLA signing is required for your Pull Request, the repository workflow may prompt you through the configured CLA process.

13. Licensing

Repository content is governed by the repository license. Contributors are responsible for ensuring that they have the legal right to submit their work under the licensing terms used by this repository.

See:

LICENSE

14. Community and Collaboration

FROG aims to build an open ecosystem around graphical dataflow programming. Constructive discussions, careful specification proposals, editorial cleanup, and serious architectural reasoning are encouraged.

The goal is not only to add more content. The goal is to build a coherent, durable, and implementable specification that can support multiple independent implementations over time. 

Contribution spirit

Be explicit.
Be architectural.
Be conservative with ownership.
Be precise with wording.
Be helpful across document boundaries.