Skip to content

About

Repository hosting the Fandango Fuzzer documentation

fandango-fuzzer.github.io/

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

169 Commits

Folders and files

NameName
Last commit message
Last commit date
_downloads
_downloads
 
 
_images
_images
 
 
_sources
_sources
 
 
_sphinx_design_static
_sphinx_design_static
 
 
_static
_static
 
 
reports
reports
 
 
.nojekyll
.nojekyll
 
 
About.html
About.html
 
 
About.html.orig
About.html.orig
 
 
About.html.rej
About.html.rej
 
 
Binary.html
Binary.html
 
 
Binary.html.orig
Binary.html.orig
 
 
Binary.html.rej
Binary.html.rej
 
 
Bits.html
Bits.html
 
 
Bits.html.orig
Bits.html.orig
 
 
Bits.html.rej
Bits.html.rej
 
 
Commands.html
Commands.html
 
 
Commands.html.orig
Commands.html.orig
 
 
Commands.html.rej
Commands.html.rej
 
 
Constraints.html
Constraints.html
 
 
Constraints.html.orig
Constraints.html.orig
 
 
Constraints.html.rej
Constraints.html.rej
 
 
Contributing.html
Contributing.html
 
 
Contributing.html.orig
Contributing.html.orig
 
 
Contributing.html.rej
Contributing.html.rej
 
 
Conventions.html
Conventions.html
 
 
Conventions.html.orig
Conventions.html.orig
 
 
Conventions.html.rej
Conventions.html.rej
 
 
Conversion.html
Conversion.html
 
 
Conversion.html.orig
Conversion.html.orig
 
 
Conversion.html.rej
Conversion.html.rej
 
 
Converters.html
Converters.html
 
 
Converters.html.orig
Converters.html.orig
 
 
Converters.html.rej
Converters.html.rej
 
 
DNS.html
DNS.html
 
 
DNS.html.orig
DNS.html.orig
 
 
DNS.html.rej
DNS.html.rej
 
 
DerivationTree.html
DerivationTree.html
 
 
DerivationTree.html.orig
DerivationTree.html.orig
 
 
DerivationTree.html.rej
DerivationTree.html.rej
 
 
Distributions.html
Distributions.html
 
 
Distributions.html.orig
Distributions.html.orig
 
 
Distributions.html.rej
Distributions.html.rej
 
 
Diversity.html
Diversity.html
 
 
Diversity.html.orig
Diversity.html.orig
 
 
Diversity.html.rej
Diversity.html.rej
 
 
FAQ.html
FAQ.html
 
 
FAQ.html.orig
FAQ.html.orig
 
 
FAQ.html.rej
FAQ.html.rej
 
 
FTP.html
FTP.html
 
 
FTP.html.orig
FTP.html.orig
 
 
FTP.html.rej
FTP.html.rej
 
 
Fanbase.html
Fanbase.html
 
 
FandangoParty.html
FandangoParty.html
 
 
FandangoParty.html.orig
FandangoParty.html.orig
 
 
FandangoParty.html.rej
FandangoParty.html.rej
 
 
FirstSpec.html
FirstSpec.html
 
 
FirstSpec.html.orig
FirstSpec.html.orig
 
 
FirstSpec.html.rej
FirstSpec.html.rej
 
 
Footer.html
Footer.html
 
 
Footer.html.orig
Footer.html.orig
 
 
Footer.html.rej
Footer.html.rej
 
 
Fuzzing.html
Fuzzing.html
 
 
Fuzzing.html.orig
Fuzzing.html.orig
 
 
Fuzzing.html.rej
Fuzzing.html.rej
 
 
Generators.html
Generators.html
 
 
Generators.html.orig
Generators.html.orig
 
 
Generators.html.rej
Generators.html.rej
 
 
Gif.html
Gif.html
 
 
Gif.html.orig
Gif.html.orig
 
 
Gif.html.rej
Gif.html.rej
 
 
HandsOn.html
HandsOn.html
 
 
HandsOn.html.orig
HandsOn.html.orig
 
 
HandsOn.html.rej
HandsOn.html.rej
 
 
Hatching.html
Hatching.html
 
 
Hatching.html.orig
Hatching.html.orig
 
 
Hatching.html.rej
Hatching.html.rej
 
 
ISO8601.html
ISO8601.html
 
 
ISO8601.html.orig
ISO8601.html.orig
 
 
ISO8601.html.rej
ISO8601.html.rej
 
 
Including.html
Including.html
 
 
Including.html.orig
Including.html.orig
 
 
Including.html.rej
Including.html.rej
 
 
Installing.html
Installing.html
 
 
Installing.html.orig
Installing.html.orig
 
 
Installing.html.rej
Installing.html.rej
 
 
Intro.html
Intro.html
 
 
Intro.html.orig
Intro.html.orig
 
 
Intro.html.rej
Intro.html.rej
 
 
Invoking.html
Invoking.html
 
 
Invoking.html.orig
Invoking.html.orig
 
 
Invoking.html.rej
Invoking.html.rej
 
 
Language.html
Language.html
 
 
Language.html.orig
Language.html.orig
 
 
Language.html.rej
Language.html.rej
 
 
LanguageServer.html
LanguageServer.html
 
 
LanguageServer.html.orig
LanguageServer.html.orig
 
 
LanguageServer.html.rej
LanguageServer.html.rej
 
 
Mp3.html
Mp3.html
 
 
Outputs.html
Outputs.html
 
 

Repository files navigation

<!DOCTYPE html>


<html lang="en" data-content_root="./" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Contributing to Fandango &#8212; Fuzzing with Fandango</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
  </script>
  <!--
    this give us a css class that will be invisible only if js is disabled
  -->
  <noscript>
    <style>
      .pst-js-only { display: none !important; }

    </style>
  </noscript>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />

    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="_static/styles/sphinx-book-theme.css?v=3c74b3bc" />
    <link rel="stylesheet" type="text/css" href="_static/togglebutton.css?v=9c3e77be" />
    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
    <link rel="stylesheet" type="text/css" href="_static/mystnb.11b39860a7a0cbfd473a3ad8a317855267ff0bd372690045ca344a6b62be495e.css" />
    <link rel="stylesheet" type="text/css" href="_static/sphinx-thebe.css?v=4fa983c6" />
    <link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" />
  
  <!-- So that users can add custom icons -->
  <script src="_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script>
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />

    <script src="_static/documentation_options.js?v=9eb32ce0"></script>
    <script src="_static/doctools.js?v=9a2dae69"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
    <script src="_static/copybutton.js?v=f281be69"></script>
    <script src="_static/scripts/sphinx-book-theme.js?v=fab101a9"></script>
    <script>let toggleHintShow = 'Click to show';</script>
    <script>let toggleHintHide = 'Click to hide';</script>
    <script>let toggleOpenOnPrint = 'true';</script>
    <script src="_static/togglebutton.js?v=b8b12719"></script>
    <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
    <script src="_static/design-tabs.js?v=f930bc37"></script>
    <script>const THEBE_JS_URL = "https://unpkg.com/thebe@0.8.2/lib/index.js"; const thebe_selector = ".thebe,.cell"; const thebe_selector_input = "pre"; const thebe_selector_output = ".output, .cell_output"</script>
    <script async="async" src="_static/sphinx-thebe.js?v=c100c467"></script>
    <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
    <script>const THEBE_JS_URL = "https://unpkg.com/thebe@0.8.2/lib/index.js"; const thebe_selector = ".thebe,.cell"; const thebe_selector_input = "pre"; const thebe_selector_output = ".output, .cell_output"</script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'Contributing';</script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Documentation Conventions" href="Conventions.html" />
    <link rel="prev" title="Fandango FAQ" href="FAQ.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
  <meta name="docsearch:version" content="" />
  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  
  <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
  
  <div id="pst-scroll-pixel-helper"></div>
  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>Back to top</button>

  
  <dialog id="pst-search-dialog">
    
<form class="bd-search d-flex align-items-center"
      action="search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         placeholder="Search this book..."
         aria-label="Search this book..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
  </dialog>

  <div class="pst-async-banner-revealer d-none">
  <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>
<aside class="bd-header-announcement" aria-label="Announcement">
  <div class="bd-header-announcement__content"><a href="https://pypi.org/project/fandango-fuzzer/1.3.1/" style="color:white;">Fandango 1.3.1</a> is now available! Check out the <a href="https://fandango-fuzzer.github.io/ReleaseNotes.html#" style="color:white;">release notes</a> for details.</div>
</aside>

  
    <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
    </header>
  

  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      
      
      <dialog id="pst-primary-sidebar-modal"></dialog>
      <div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
        

  
  <div class="sidebar-header-items sidebar-primary__section">
    
    
    
    
  </div>
  
    <div class="sidebar-primary-items__start sidebar-primary__section">
        <div class="sidebar-primary-item">

  
    
  

<a class="navbar-brand logo" href="index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="_static/fandango.png" class="logo__image only-light" alt="Fuzzing with Fandango - Home"/>
    <img src="_static/fandango.png" class="logo__image only-dark pst-js-only" alt="Fuzzing with Fandango - Home"/>
  
  
</a></div>
        <div class="sidebar-primary-item">

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button></div>
        <div class="sidebar-primary-item"><nav class="bd-links bd-docs-nav" aria-label="Main">
    <div class="bd-toc-item navbar-nav active">
        
        <ul class="nav bd-sidenav bd-sidenav__home-link">
            <li class="toctree-l1">
                <a class="reference internal" href="index.html">
                    Fuzzing with Fandango
                </a>
            </li>
        </ul>
        <p aria-level="2" class="caption" role="heading"><span class="caption-text">About Fandango</span></p>
<ul class="current nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="About.html">About Fandango</a></li>
<li class="toctree-l1"><a class="reference internal" href="ReleaseNotes.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="FAQ.html">Fandango FAQ</a></li>
<li class="toctree-l1 current active"><a class="current reference internal" href="#">Contributing to Fandango</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">First Steps</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Conventions.html">Documentation Conventions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Setup.html">Installing Fandango</a></li>
<li class="toctree-l1"><a class="reference internal" href="FirstSpec.html">A First Fandango Spec</a></li>
<li class="toctree-l1"><a class="reference internal" href="Invoking.html">Invoking Fandango</a></li>
<li class="toctree-l1"><a class="reference internal" href="Fuzzing.html">Fuzzing with Fandango</a></li>
<li class="toctree-l1"><a class="reference internal" href="Strategies.html">Some Fuzzing Strategies</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Hands-On</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="HandsOn.html">Hands-On: Fuzzing a Protocol End to End</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Advanced Input Generation</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Constraints.html">Shaping Inputs with Constraints</a></li>
<li class="toctree-l1"><a class="reference internal" href="Shell.html">The Fandango Shell</a></li>
<li class="toctree-l1"><a class="reference internal" href="Generators.html">Data Generators and Fakers</a></li>
<li class="toctree-l1"><a class="reference internal" href="Regexes.html">Regular Expressions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Recursive.html">Complex Input Structures</a></li>
<li class="toctree-l1"><a class="reference internal" href="Paths.html">Accessing Input Elements</a></li>
<li class="toctree-l1"><a class="reference internal" href="Converters.html">Converting ANTLR and Other Input Specs</a></li>
<li class="toctree-l1"><a class="reference internal" href="Diversity.html">Covering Specs and Code</a></li>
<li class="toctree-l1"><a class="reference internal" href="ISO8601.html">Case Study: ISO 8601 Date + Time</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Generating Binary Inputs</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Binary.html">Generating Binary Inputs</a></li>
<li class="toctree-l1"><a class="reference internal" href="Bits.html">Bits and Bit Fields</a></li>
<li class="toctree-l1"><a class="reference internal" href="Conversion.html">Data Converters</a></li>
<li class="toctree-l1"><a class="reference internal" href="Png.html">Case Study: PNG</a></li>
<li class="toctree-l1"><a class="reference internal" href="Gif.html">Case Study: GIF</a></li>
<li class="toctree-l1"><a class="reference internal" href="Mp3.html">Case Study: MP3</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Checking Responses</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Parsing.html">Parsing Strings</a></li>
<li class="toctree-l1"><a class="reference internal" href="Outputs.html">Checking Outputs</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Testing Protocols</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Protocols.html">Testing Protocols</a></li>
<li class="toctree-l1"><a class="reference internal" href="Parties.html">Customizing Party Communication</a></li>
<li class="toctree-l1"><a class="reference internal" href="FTP.html">Case Study: FTP</a></li>
<li class="toctree-l1"><a class="reference internal" href="DNS.html">Case Study: DNS</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Hatching Specs</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Hatching.html">Hatching Specs</a></li>
<li class="toctree-l1"><a class="reference internal" href="Style.html">Fandango Style Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="Fanbase.html">Fandango and Fanbase</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Fandango Reference</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Reference.html">Fandango Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="Installing.html">Installing Fandango</a></li>
<li class="toctree-l1"><a class="reference internal" href="Commands.html">Fandango Command Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="Language.html">Fandango Language Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="Stdlib.html">Fandango Standard Library</a></li>
<li class="toctree-l1"><a class="reference internal" href="DerivationTree.html">Derivation Tree Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="PythonAPI.html">Python API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="FandangoParty.html">FandangoParty Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="Including.html">Fandango File Locations</a></li>
<li class="toctree-l1"><a class="reference internal" href="LanguageServer.html">Fandango Language Server</a></li>
</ul>

    </div>
</nav></div>
    </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
      <div class="sidebar-primary-item">
<div id="ethical-ad-placement"
      class="flat"
      data-ea-publisher="readthedocs"
      data-ea-type="readthedocs-sidebar"
      data-ea-manual="true">
</div></div>
  </div>


      </div>
      
      <main id="main-content" class="bd-main" role="main">
        
        

<div class="sbt-scroll-pixel-helper"></div>

          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item"><button class="sidebar-toggle primary-toggle btn btn-sm" title="Toggle primary sidebar" data-bs-placement="bottom" data-bs-toggle="tooltip">
  <span class="fa-solid fa-bars"></span>
</button></div>
      
    </div>
  
  
    <div class="header-article-items__end">
      
        <div class="header-article-item">

<div class="article-header-buttons">





<div class="dropdown dropdown-source-buttons">
  <button class="btn dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-label="Source repositories">
    <i class="fab fa-github"></i>
  </button>
  <ul class="dropdown-menu">
      
      
      
      <li><a href="https://github.com/fandango-fuzzer/fandango" target="_blank"
   class="btn btn-sm btn-source-repository-button dropdown-item"
   title="Source repository"
   data-bs-placement="left" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fab fa-github"></i>
  </span>
<span class="btn__text-container">Repository</span>
</a>
</li>
      
      
      
      
      <li><a href="https://github.com/fandango-fuzzer/fandango/issues/new?title=Issue%20on%20page%20%2FContributing.html&body=Your%20issue%20content%20here." target="_blank"
   class="btn btn-sm btn-source-issues-button dropdown-item"
   title="Open an issue"
   data-bs-placement="left" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-lightbulb"></i>
  </span>
<span class="btn__text-container">Open issue</span>
</a>
</li>
      
  </ul>
</div>






<div class="dropdown dropdown-download-buttons">
  <button class="btn dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-label="Download this page">
    <i class="fas fa-download"></i>
  </button>
  <ul class="dropdown-menu">
      
      
      
      <li><a href="_sources/Contributing.md" target="_blank"
   class="btn btn-sm btn-download-source-button dropdown-item"
   title="Download source file"
   data-bs-placement="left" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-file"></i>
  </span>
<span class="btn__text-container">.md</span>
</a>
</li>
      
      
      
      
      <li>
<a href="_static/fandango.pdf" target="_blank"
  class="btn btn-sm btn-download-pdf-button dropdown-item"
  title="Download PDF"
  data-bs-placement="left" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-file-pdf"></i>
  </span>
<span class="btn__text-container">.pdf</span>
</a>
</li>
      
  </ul>
</div>




<button onclick="toggleFullScreen()"
  class="btn btn-sm btn-fullscreen-button pst-navbar-icon"
  title="Fullscreen mode"
  data-bs-placement="bottom" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-expand"></i>
  </span>

</button>



<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button>


<button class="btn btn-sm pst-navbar-icon search-button search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
</button>
<button class="sidebar-toggle secondary-toggle btn btn-sm pst-navbar-icon" title="Toggle secondary sidebar" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="fa-solid fa-list"></span>
</button>
</div></div>
      
    </div>
  
</div>
</div>
              
              

<div id="jb-print-docs-body" class="onlyprint">
    <h1>Contributing to Fandango</h1>
    <!-- Table of contents -->
    <div id="print-main-content">
        <div id="jb-print-toc">
            
            <div>
                <h2> Contents </h2>
            </div>
            <nav aria-label="Page">
                <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#code-of-conduct">Code of Conduct</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#ways-to-contribute">Ways to Contribute</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#reporting-bugs">Reporting Bugs</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#first-time-contributors">First Time Contributors</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#setting-up-a-development-environment">Setting Up a Development Environment</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-1-fork-and-clone">Step 1: Fork and clone</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-2-install-the-system-tools">Step 2: Install the system tools</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-3-install-fandango-with-uv">Step 3: Install Fandango with <code class="docutils literal notranslate"><span class="pre">uv</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-3-alternative-install-with-pip">Step 3, alternative: Install with <code class="docutils literal notranslate"><span class="pre">pip</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#if-the-build-fails">If the build fails</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#running-tests">Running Tests</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#pre-commit">Pre-commit</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#what-ci-checks">What CI Checks</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#lockfiles">Lockfiles</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-ai-assistance">Using AI Assistance</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#contributing-code">Contributing Code</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#licensing-of-contributions">Licensing of Contributions</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#changing-the-parser">Changing the Parser</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#contributing-to-the-documentation">Contributing to the Documentation</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#attributions">Attributions</a></li>
</ul>
            </nav>
        </div>
    </div>
</div>

              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="contributing-to-fandango">
<span id="sec-contributing"></span><h1>Contributing to Fandango<a class="headerlink" href="#contributing-to-fandango" title="Link to this heading">#</a></h1>
<p>Welcome! Fandango is a community project that aims to work for a wide range of
developers. If you are trying out Fandango, your experience and what you can
contribute are important to the project’s success.</p>
<p>This page covers everything from reporting a bug to getting a pull request
merged. If you only want to <em>use</em> Fandango, see <a class="reference internal" href="Installing.html#sec-installing"><span class="std std-ref">Installing</span></a>
instead.</p>
<section id="code-of-conduct">
<span id="sec-code-of-conduct"></span><h2>Code of Conduct<a class="headerlink" href="#code-of-conduct" title="Link to this heading">#</a></h2>
<p>Everyone participating in Fandango, and in particular in our issue tracker,
pull requests, and chat, is expected to treat other people with respect and to
follow the <a class="reference external" href="https://www.python.org/psf/codeofconduct/">Python Community Code of
Conduct</a>.</p>
<p>If you experience or witness unacceptable behaviour, report it to
<a class="reference external" href="mailto:fandango-fuzzer&#37;&#52;&#48;protonmail&#46;com">fandango-fuzzer<span>&#64;</span>protonmail<span>&#46;</span>com</a>. Reports
are handled confidentially. See
<a class="reference external" href="https://github.com/fandango-fuzzer/fandango/blob/main/CODE_OF_CONDUCT.md"><code class="docutils literal notranslate"><span class="pre">CODE_OF_CONDUCT.md</span></code></a>
in the repository root.</p>
</section>
<section id="ways-to-contribute">
<span id="sec-ways-to-contribute"></span><h2>Ways to Contribute<a class="headerlink" href="#ways-to-contribute" title="Link to this heading">#</a></h2>
<p>You do not have to write code to help.</p>
<ul class="simple">
<li><p><strong>Report a bug.</strong> See <a class="reference internal" href="#sec-reporting-bugs"><span class="std std-ref">reporting bugs</span></a> below.</p></li>
<li><p><strong>Request a feature</strong>, or tell us where Fandango was confusing to use.</p></li>
<li><p><strong>Improve the documentation.</strong> This book is part of the repository, and doc
fixes are among the most useful contributions we get.</p></li>
<li><p><strong>Fix an issue.</strong> Browse the <a class="reference external" href="https://github.com/fandango-fuzzer/fandango/issues">issue
tracker</a> and pick
something up.</p></li>
</ul>
<p>For security vulnerabilities, do <strong>not</strong> open a public issue. Report them
privately through GitHub’s <a class="reference external" href="https://github.com/fandango-fuzzer/fandango/security/advisories/new">security advisory form</a>, reachable from the
repository’s Security tab, so the report, the fix, and the advisory stay in one
private thread. See
<a class="reference external" href="https://github.com/fandango-fuzzer/fandango/blob/main/SECURITY.md"><code class="docutils literal notranslate"><span class="pre">SECURITY.md</span></code></a>.</p>
</section>
<section id="reporting-bugs">
<span id="sec-reporting-bugs"></span><h2>Reporting Bugs<a class="headerlink" href="#reporting-bugs" title="Link to this heading">#</a></h2>
<p>A good report is one someone else can reproduce. Please include:</p>
<ul class="simple">
<li><p><strong>What you did</strong>: the <code class="docutils literal notranslate"><span class="pre">.fan</span></code> spec (reduced to the smallest one that still
shows the problem) and the exact command you ran.</p></li>
<li><p><strong>What you expected</strong> to happen, and <strong>what happened instead</strong>, including the
full error message and traceback.</p></li>
<li><p><strong>Your environment</strong>: the output of <code class="docutils literal notranslate"><span class="pre">fandango</span> <span class="pre">--version</span></code>, your Python version,
and your operating system.</p></li>
</ul>
<p>A spec that is a hundred lines long makes a bug much harder to act on than one
that is five. Time spent reducing the input is usually time saved overall.</p>
</section>
<section id="first-time-contributors">
<span id="sec-first-time-contributors"></span><h2>First Time Contributors<a class="headerlink" href="#first-time-contributors" title="Link to this heading">#</a></h2>
<p>If you are not yet fluent in Fandango’s specification language, the fastest way
in is the <a class="reference internal" href="HandsOn.html#sec-handson"><span class="std std-ref">hands-on tutorial</span></a>. It builds one small protocol from
random bytes up to a stateful conversation, and by the end you will have written
the grammars, constraints, and feedback that most issues are about. It takes an
afternoon and it is the same material we would otherwise explain in review.</p>
<p>If you are looking for something to work on, browse the <a class="reference external" href="https://github.com/fandango-fuzzer/fandango/issues">issue
tracker</a>.</p>
<p><strong>Check whether the issue is assigned before you start.</strong> If it already has an
assignee, someone is working on it, so please pick a different one. Duplicated
effort is wasted effort, and it is discouraging for whoever got there first.</p>
<p><strong>If it is unassigned, say so in the issue before you begin</strong>, and wait to be
assigned. A short comment is enough. This is not bureaucracy: it lets us tell
you if the issue is more involved than it looks, if it is already being
addressed elsewhere, or if we have a view on the approach. All of that is much
cheaper to hear before you write the code than after.</p>
<p>Once the issue is yours, fix it, <a class="reference internal" href="#sec-running-tests"><span class="std std-ref">add a test</span></a>, and open a
pull request.</p>
<p>To get help with a specific issue, comment on the issue itself, and say what you
have already tried and where you have looked. If you find you cannot finish
something you claimed, just say so in the issue and unassign yourself. That is
completely fine and much better than an issue going quiet.</p>
<p>If your change is going to be a significant amount of work, open an issue first
describing what you intend to do. That way a conversation can happen early,
before you have written code that someone disagrees with.</p>
</section>
<section id="setting-up-a-development-environment">
<span id="sec-getting-started-with-development"></span><h2>Setting Up a Development Environment<a class="headerlink" href="#setting-up-a-development-environment" title="Link to this heading">#</a></h2>
<p>Fandango requires <strong>Python 3.11 or later</strong>. Our CI tests against Python 3.11,
3.12, 3.13, and 3.14 on Linux, macOS, and Windows.</p>
<section id="step-1-fork-and-clone">
<h3>Step 1: Fork and clone<a class="headerlink" href="#step-1-fork-and-clone" title="Link to this heading">#</a></h3>
<p>You do not need push access to the Fandango repository, and you should not wait
for it. All your work happens on your own fork, and reaches us as a <a class="reference internal" href="#sec-contributing-code"><span class="std std-ref">pull
request across forks</span></a>.</p>
<p>Fork the <a class="reference external" href="https://github.com/fandango-fuzzer/fandango">Fandango repository</a> on
GitHub, then clone your fork:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/YOUR-USERNAME/fandango.git
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>fandango
</pre></div>
</div>
</section>
<section id="step-2-install-the-system-tools">
<h3>Step 2: Install the system tools<a class="headerlink" href="#step-2-install-the-system-tools" title="Link to this heading">#</a></h3>
<p>Fandango’s parser is generated with ANTLR and compiled with a C++ compiler.
Install both:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>system-dev-tools
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This installs system packages (via Homebrew, apt, or Chocolatey depending on
your platform), so it may ask for your password.</p>
</div>
</section>
<section id="step-3-install-fandango-with-uv">
<span id="sec-uv-install"></span><h3>Step 3: Install Fandango with <code class="docutils literal notranslate"><span class="pre">uv</span></code><a class="headerlink" href="#step-3-install-fandango-with-uv" title="Link to this heading">#</a></h3>
<p>We recommend <a class="reference external" href="https://docs.astral.sh/uv/">uv</a>. It creates the virtual
environment and installs the exact dependency set our CI uses, taken from
<code class="docutils literal notranslate"><span class="pre">uv.lock</span></code>:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>uv<span class="w"> </span>sync<span class="w"> </span>--all-extras<span class="w"> </span>--locked
</pre></div>
</div>
<p>That is the whole setup. Run Fandango with <code class="docutils literal notranslate"><span class="pre">uv</span> <span class="pre">run</span> <span class="pre">fandango</span></code>, or activate the
environment it created:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nb">source</span><span class="w"> </span>.venv/bin/activate
</pre></div>
</div>
<p>On Windows, use <code class="docutils literal notranslate"><span class="pre">.venv\Scripts\activate</span></code>.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>Because <code class="docutils literal notranslate"><span class="pre">--locked</span></code> pins every dependency to the versions our CI resolved, this
is also the fastest way to rule out a dependency problem when something behaves
differently for you than for us.</p>
</div>
</section>
<section id="step-3-alternative-install-with-pip">
<span id="sec-pip-install"></span><h3>Step 3, alternative: Install with <code class="docutils literal notranslate"><span class="pre">pip</span></code><a class="headerlink" href="#step-3-alternative-install-with-pip" title="Link to this heading">#</a></h3>
<p>If you would rather not use <code class="docutils literal notranslate"><span class="pre">uv</span></code>, create a virtual environment and install
Fandango into it as an editable package:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>.venv
$<span class="w"> </span><span class="nb">source</span><span class="w"> </span>.venv/bin/activate
$<span class="w"> </span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span><span class="s2">&quot;.[full]&quot;</span>
</pre></div>
</div>
<p>On Windows, create and activate the environment with:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>python<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>.venv
$<span class="w"> </span>.venv<span class="se">\S</span>cripts<span class="se">\a</span>ctivate
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">full</span></code> extra pulls in everything you need to develop: it is shorthand for
<code class="docutils literal notranslate"><span class="pre">book</span></code>, <code class="docutils literal notranslate"><span class="pre">development</span></code>, and <code class="docutils literal notranslate"><span class="pre">test</span></code>. To install a subset instead, name the ones
you want, for example <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">&quot;.[test]&quot;</span></code>.</p>
<div class="pst-scrollable-table-container"><table class="table">
<thead>
<tr class="row-odd"><th class="head"><p>Extra</p></th>
<th class="head"><p>Gives you</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">test</span></code></p></td>
<td><p>the unit test suite and its fixtures</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">development</span></code></p></td>
<td><p>Ruff, mypy, and the other code-quality tools</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">book</span></code></p></td>
<td><p>everything needed to build this documentation</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">full</span></code></p></td>
<td><p>all three of the above</p></td>
</tr>
</tbody>
</table>
</div>
<p>Reset your shell’s command lookup afterwards, so <code class="docutils literal notranslate"><span class="pre">fandango</span></code> resolves to your
copy (not needed on Windows):</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nb">hash</span><span class="w"> </span>-r
</pre></div>
</div>
</section>
<section id="if-the-build-fails">
<h3>If the build fails<a class="headerlink" href="#if-the-build-fails" title="Link to this heading">#</a></h3>
<p>The C++ parser is the usual culprit, because it needs ANTLR and a working C++
toolchain. You can skip it entirely:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nv">FANDANGO_SKIP_CPP_PARSER</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>uv<span class="w"> </span>sync<span class="w"> </span>--all-extras<span class="w"> </span>--locked
</pre></div>
</div>
<p>Fandango then falls back to the pure-Python parser. Everything still works and
parsing is slower, which is fine for most development.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">system-dev-tools</span></code> is what installs the toolchain the C++ parser needs. If
you skipped it in Step 2, that is the first thing to try.</p>
</div>
<p>That’s it. You have installed your personal copy of Fandango, you can invoke it
as <code class="docutils literal notranslate"><span class="pre">fandango</span></code>, and you can change its code as you like.</p>
</section>
</section>
<section id="running-tests">
<span id="sec-running-tests"></span><h2>Running Tests<a class="headerlink" href="#running-tests" title="Link to this heading">#</a></h2>
<p>Running the full suite takes a while and is usually not necessary while
preparing a pull request. Once you open one, the full suite runs on GitHub and
you can fix anything it catches.</p>
<p>To run it yourself:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>tests
</pre></div>
</div>
<p>or equivalently:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pytest
</pre></div>
</div>
<p>The suite runs in parallel by default via
<a class="reference external" href="https://pytest-xdist.readthedocs.io/en/stable/">pytest-xdist</a>. To run a single
test file while working on it:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pytest<span class="w"> </span>tests/test_some_file.py<span class="w"> </span>-x
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">test</span></code> (singular) is not the test target and does nothing. Use <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">tests</span></code>.</p>
</div>
</section>
<section id="pre-commit">
<span id="sec-pre-commit"></span><h2>Pre-commit<a class="headerlink" href="#pre-commit" title="Link to this heading">#</a></h2>
<p>Fandango ships a <code class="docutils literal notranslate"><span class="pre">pre-commit</span></code> configuration that catches most of what CI checks,
before you push:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>pre-commit
$<span class="w"> </span>pre-commit<span class="w"> </span>install
</pre></div>
</div>
<p>The hooks run Ruff formatting, Ruff linting, mypy (including <code class="docutils literal notranslate"><span class="pre">--strict</span></code> on
<code class="docutils literal notranslate"><span class="pre">src</span></code>), and the lockfile checks described below.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <a class="reference internal" href="#sec-running-tests"><span class="std std-ref">tests</span></a> are not part of pre-commit, because they take
too long. Run them yourself.</p>
</div>
</section>
<section id="what-ci-checks">
<span id="sec-ci-checks"></span><h2>What CI Checks<a class="headerlink" href="#what-ci-checks" title="Link to this heading">#</a></h2>
<p>Every pull request runs the following. Knowing this list saves a round trip,
since these are the things that most often turn a pull request red:</p>
<div class="pst-scrollable-table-container"><table class="table">
<thead>
<tr class="row-odd"><th class="head"><p>Check</p></th>
<th class="head"><p>Command</p></th>
<th class="head"><p>Scope</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Formatting</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ruff</span> <span class="pre">format</span> <span class="pre">--check</span> <span class="pre">.</span></code></p></td>
<td><p>the <strong>whole repository</strong>, not just <code class="docutils literal notranslate"><span class="pre">src</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Linting</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ruff</span> <span class="pre">check</span> <span class="pre">src</span> <span class="pre">tests</span> <span class="pre">evaluation</span> <span class="pre">scripts</span></code></p></td>
<td><p>those four directories</p></td>
</tr>
<tr class="row-even"><td><p>Types</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">mypy</span> <span class="pre">.</span></code> and <code class="docutils literal notranslate"><span class="pre">mypy</span> <span class="pre">--strict</span> <span class="pre">src</span></code></p></td>
<td><p>the whole repository, then <code class="docutils literal notranslate"><span class="pre">src</span></code> strictly</p></td>
</tr>
<tr class="row-odd"><td><p>Tests</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">pytest</span></code></p></td>
<td><p>Python 3.11 to 3.14, on Linux, macOS, and Windows</p></td>
</tr>
<tr class="row-even"><td><p>Docs</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">web</span></code></p></td>
<td><p>the whole book must build</p></td>
</tr>
<tr class="row-odd"><td><p>Lockfiles</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">uv</span> <span class="pre">lock</span> <span class="pre">--check</span></code> and a <code class="docutils literal notranslate"><span class="pre">pylock.toml</span></code> diff</p></td>
<td><p>see below</p></td>
</tr>
</tbody>
</table>
</div>
<p>The formatting and type checks cover the entire repository, so a stray file
outside <code class="docutils literal notranslate"><span class="pre">src</span></code> can fail the build. Running <code class="docutils literal notranslate"><span class="pre">pre-commit</span></code> locally catches almost
all of it.</p>
<section id="lockfiles">
<span id="sec-lockfiles"></span><h3>Lockfiles<a class="headerlink" href="#lockfiles" title="Link to this heading">#</a></h3>
<p>We keep both lockfiles current, for reproducible environments and for
compatibility with the wider Python ecosystem:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">uv.lock</span></code> is generated by <code class="docutils literal notranslate"><span class="pre">uv</span></code> and is the source of truth for the dependency
set. Update it with <code class="docutils literal notranslate"><span class="pre">uv</span> <span class="pre">lock</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pylock.toml</span></code> is derived from <code class="docutils literal notranslate"><span class="pre">uv.lock</span></code> so that other tools can consume it.
Update it with <code class="docutils literal notranslate"><span class="pre">uv</span> <span class="pre">export</span> <span class="pre">--output-file=pylock.toml</span> <span class="pre">--all-extras</span> <span class="pre">--locked</span></code>.</p></li>
</ul>
<p>After changing dependencies in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>, regenerate both:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>lock
</pre></div>
</div>
<p>Both pre-commit and CI check that these are in sync, so forgetting this step
fails the build.</p>
</section>
</section>
<section id="using-ai-assistance">
<span id="sec-ai-assistance"></span><h2>Using AI Assistance<a class="headerlink" href="#using-ai-assistance" title="Link to this heading">#</a></h2>
<p>We are not against AI tools. Plenty of good contributions are written with a
model in the loop, and we use them ourselves.</p>
<p>Two things we ask.</p>
<p><strong>Tell us when you used one.</strong> If a change was substantially written with AI
assistance, say so in the pull request. We cannot verify it and it will not
count against you. It tells a reviewer what kind of read the change needs, which
makes triage faster for everyone.</p>
<p><strong>Write the description yourself.</strong> Generated pull request and issue
descriptions tend to be long and say little, which moves work onto the reader.
Writing it in your own words is also the quickest way to find out whether you
understand the change.</p>
<p>And one thing we require: <strong>you own the code you submit</strong>. You should be able to
say why the change is written the way it is, why it is correct, what
alternatives you rejected, and what happens at the edges. If a reviewer asks
about a decision and the honest answer would be “the model wrote it that way”,
the pull request is not ready to open.</p>
<p>The problem we care about is not AI. It is <strong>moving your work onto the
maintainers</strong>. A patch produced by pasting an issue into a model and pushing the
result, without reading it, running it, or understanding it, costs us more time
than the issue would have. Reviewing that means reconstructing an intent that
was never formed in the first place, which is harder than writing the fix from
scratch. That is not a contribution, it is a transfer of effort.</p>
<p>Keep the diff minimal while you are at it. Models like to reformat, rename, and
“improve” code the change never needed to touch, and every unrelated hunk is
more for a reviewer to read and rule out.</p>
<p>So before you open a pull request, whatever tools you used to get there:</p>
<ul class="simple">
<li><p>Have you read every line you are about to submit, and do you understand what
each one does and why it is there?</p></li>
<li><p>Have you run it, and does your test actually fail without the change?</p></li>
<li><p>Is the diff limited to what the change requires?</p></li>
</ul>
</section>
<section id="contributing-code">
<span id="sec-contributing-code"></span><h2>Contributing Code<a class="headerlink" href="#contributing-code" title="Link to this heading">#</a></h2>
<p>We use the usual GitHub pull request flow, from a fork:</p>
<ol class="arabic">
<li><p><strong>Fork</strong> the <a class="reference external" href="https://github.com/fandango-fuzzer/fandango">Fandango
repository</a> on GitHub. This
gives you your own copy, at <code class="docutils literal notranslate"><span class="pre">https://github.com/YOUR-USERNAME/fandango</span></code>.</p></li>
<li><p><strong>Clone your fork</strong> and set it up as described in <a class="reference internal" href="#sec-getting-started-with-development"><span class="std std-ref">Setting up a development
environment</span></a>.</p></li>
<li><p><strong>Commit your change on a branch</strong> in your fork, and push that branch:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>git<span class="w"> </span>switch<span class="w"> </span>-c<span class="w"> </span>my-change
$<span class="w"> </span>git<span class="w"> </span>commit<span class="w"> </span>-am<span class="w"> </span><span class="s2">&quot;Say what changed and why&quot;</span>
$<span class="w"> </span>git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>origin<span class="w"> </span>my-change
</pre></div>
</div>
</li>
<li><p><strong>Open a pull request across forks</strong>: from your branch on your fork, to
<code class="docutils literal notranslate"><span class="pre">main</span></code> on <code class="docutils literal notranslate"><span class="pre">fandango-fuzzer/fandango</span></code>. GitHub offers this on your fork’s page
right after you push, and you can also open it from the <a class="reference external" href="https://github.com/fandango-fuzzer/fandango/compare">main
repository</a> by picking
your fork and branch as the source.</p></li>
</ol>
<p>Branches on the main repository itself are for the core developers, so this is
the route for everyone else, and it needs nothing from us to get started.</p>
<p>If any of this is unfamiliar, see <a class="reference external" href="https://docs.github.com/en/pull-requests">GitHub’s
documentation</a>.</p>
<p>Anyone interested in Fandango may review your code, and one of the core
developers merges it when they think it is ready.</p>
<p><strong>What makes a pull request easy to merge:</strong></p>
<ul class="simple">
<li><p>It does <strong>one thing</strong>. A focused change is far easier to review than a large
one, and reviewability is usually what decides how fast something lands.</p></li>
<li><p>It says <strong>what</strong> it changes and <strong>why</strong>. The why matters more; the diff
already shows the what.</p></li>
<li><p>It comes with <strong>tests</strong> for any behaviour it changes. A regression test that
fails before your fix and passes after is the most convincing thing you can
include.</p></li>
<li><p>It <strong>updates the documentation</strong> when it changes something a user can see.</p></li>
<li><p>It is <strong>green in CI</strong>.</p></li>
</ul>
<p>If a review asks for changes, push additional commits to the same branch rather
than force-pushing a rewritten history. That keeps the review comments anchored
to the code they refer to.</p>
<p>Pull requests are merged with a merge commit, so the commits on your branch stay
in the project history. They do not need to be perfect, but a reader six months
from now benefits from commit messages that say what changed and why.</p>
<section id="licensing-of-contributions">
<span id="sec-contribution-licensing"></span><h3>Licensing of Contributions<a class="headerlink" href="#licensing-of-contributions" title="Link to this heading">#</a></h3>
<p>Fandango is released under the <a class="reference external" href="https://github.com/fandango-fuzzer/fandango/blob/main/LICENSE.md">European Union Public Licence v1.2</a>.
By contributing, you agree that your contribution is licensed under those same
terms, and you confirm that you have the right to submit it.</p>
</section>
<section id="changing-the-parser">
<h3>Changing the Parser<a class="headerlink" href="#changing-the-parser" title="Link to this heading">#</a></h3>
<p>If your contribution changes the ANTLR <code class="docutils literal notranslate"><span class="pre">.g4</span></code> files, you have to regenerate and
recompile the parser. This needs a C++ compiler such as <code class="docutils literal notranslate"><span class="pre">clang</span></code>.</p>
<p>Regenerate the parser code:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>parser
</pre></div>
</div>
<p>Then reinstall Fandango, which recompiles it: see <a class="reference internal" href="#sec-uv-install"><span class="std std-ref">installing with
uv</span></a> or <a class="reference internal" href="#sec-pip-install"><span class="std std-ref">with pip</span></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If compiling the C++ parser fails, Fandango falls back to the slower Python
parser, so this is not a hard blocker for testing your change.</p>
</div>
</section>
<section id="contributing-to-the-documentation">
<h3>Contributing to the Documentation<a class="headerlink" href="#contributing-to-the-documentation" title="Link to this heading">#</a></h3>
<p>This book lives in <code class="docutils literal notranslate"><span class="pre">docs/</span></code> in the repository. Preview your changes before
opening a pull request:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>html
</pre></div>
</div>
<p>The result lands in <code class="docutils literal notranslate"><span class="pre">docs/_build/html</span></code>. Because CI builds the book on every
pull request, a broken directive or a dead cross-reference fails the build, so
it is worth checking locally.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>The book executes many of its own code examples while building. If your change
touches an executed example, build the book to confirm the output is still what
the page claims.</p>
</div>
</section>
</section>
<section id="attributions">
<h2>Attributions<a class="headerlink" href="#attributions" title="Link to this heading">#</a></h2>
<p>This guide was originally forked from the <a class="reference external" href="https://github.com/python/mypy/blob/master/CONTRIBUTING.md">mypy contribution
guide</a>, which is
licensed under the terms of the MIT license.</p>
</section>
</section>

    <script type="text/x-thebe-config">
    {
        requestKernel: true,
        binderOptions: {
            repo: "binder-examples/jupyter-stacks-datascience",
            ref: "master",
        },
        codeMirrorConfig: {
            theme: "abcdef",
            mode: "python"
        },
        kernelOptions: {
            name: "python3",
            path: "./."
        },
        predefinedOutput: true
    }
    </script>
    <script>kernelName = 'python3'</script>

                </article>
              

              
              
              
              
                <footer class="prev-next-footer d-print-none">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="FAQ.html"
       title="previous page">
      <i class="fa-solid fa-angle-left"></i>
      <div class="prev-next-info">
        <p class="prev-next-subtitle">previous</p>
        <p class="prev-next-title">Fandango FAQ</p>
      </div>
    </a>
    <a class="right-next"
       href="Conventions.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Documentation Conventions</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            
              
                <dialog id="pst-secondary-sidebar-modal"></dialog>
                <div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item"><div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> Contents
  </div>
  <nav id="pst-page-toc-nav" class="page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#code-of-conduct">Code of Conduct</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#ways-to-contribute">Ways to Contribute</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#reporting-bugs">Reporting Bugs</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#first-time-contributors">First Time Contributors</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#setting-up-a-development-environment">Setting Up a Development Environment</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-1-fork-and-clone">Step 1: Fork and clone</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-2-install-the-system-tools">Step 2: Install the system tools</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-3-install-fandango-with-uv">Step 3: Install Fandango with <code class="docutils literal notranslate"><span class="pre">uv</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#step-3-alternative-install-with-pip">Step 3, alternative: Install with <code class="docutils literal notranslate"><span class="pre">pip</span></code></a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#if-the-build-fails">If the build fails</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#running-tests">Running Tests</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#pre-commit">Pre-commit</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#what-ci-checks">What CI Checks</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#lockfiles">Lockfiles</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-ai-assistance">Using AI Assistance</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#contributing-code">Contributing Code</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#licensing-of-contributions">Licensing of Contributions</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#changing-the-parser">Changing the Parser</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#contributing-to-the-documentation">Contributing to the Documentation</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#attributions">Attributions</a></li>
</ul>
  </nav></div>

</div></div>
              
            
          </div>
          <footer class="bd-footer-content">
            
<div class="bd-footer-content__inner container">
  
  <div class="footer-item">
    
<p class="component-author">
By José Antonio Zamudio Amaya, Valentin Huber, Alexander Liggesmeyer, Marius Smytzek, and Andreas Zeller
</p>

  </div>
  
  <div class="footer-item">
    

  <p class="copyright">
    
      © Copyright 2024-2026 CISPA Helmholtz Center for Information Security (www.cispa.de). All Rights Reserved..
      <br/>
    
  </p>

  </div>
  
  <div class="footer-item">
    
  </div>
  
  <div class="footer-item">
    
  </div>
  
</div>
          </footer>
        

      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script defer src="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></script>

  <footer class="bd-footer">
  </footer>
  </body>
</html>

About

Repository hosting the Fandango Fuzzer documentation

fandango-fuzzer.github.io/

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages