<mental_model> MELPA's package-build derives the distributable artifacts from your source; it does not ship your working tree verbatim. It generates the package descriptor (NAME-pkg.el) from headers in the main library, generates autoloads, and stamps a version from the repository. Anything the build generates is something you should not author or commit, because a committed copy either gets overwritten or, worse, ships stale and conflicts with the generated one. Treat the main library's comment headers as the single source of truth for package metadata. Everything else about identity (descriptor, autoloads, version) flows from there mechanically.

<recipe_format> A recipe is a single file in the archive's recipes/ directory, named exactly after the package (no extension). Its contents are one Lisp form: (NAME :fetcher ... KEYWORDS...). The filename must equal the package name and the main library's feature name.

    ;; Copyright (C) 2026  Author Name

    ;; Author: Author Name &lt;author@example.com&gt;
    ;; Maintainer: Author Name &lt;author@example.com&gt;
    ;; URL: https://github.com/owner/foo
    ;; Version: 1.2.0
    ;; Keywords: convenience tools
    ;; Package-Requires: ((emacs "29.1") (dash "2.19"))

    ;; This file is NOT part of GNU Emacs.

    ;; This program is free software: you can redistribute it and/or modify
    ;; ... (full GPLv3 notice) ...

    ;;; Commentary:
    ;;
    ;; One or more paragraphs describing what the package does.

    ;;; Code:

    ;; ... definitions ...

    (provide 'foo)
    ;;; foo.el ends here
  </code>
  <notes>
    <item>Summary line `;;; foo.el --- description` must stay under 80 characters, with the `lexical-binding` cookie in the `-*- -*-` block.</item>
    <item>`Keywords` are space-separated and should be drawn from the standard finder keyword list (`M-x finder-list-keywords`); place them before `Package-Requires`.</item>
    <item>End the file with `(provide 'foo)` followed by the `;;; foo.el ends here` footer line; both are checkdoc/package-lint expectations.</item>
  </notes>
</example>

<static_checks> What the two required tools actually verify. Run both on every shipped file before submitting. These are the concrete failures you will see, distinct from human-review style requests.

<review_findings> Recurring items raised in MELPA human review and by package-lint/checkdoc. Split them into blocking (the recipe will not be accepted, or the package misbehaves) and deferrable (style or design calls that can wait). Do not silence a finding by weakening a real design decision; record why it is deferred instead.

<anti_patterns> Checking in NAME-pkg.el or generated autoloads because "the build needs them". Let package-build generate them. Keep only source; exclude any local generated copies via :files.

<decision_tree name="files_property"> Do you need a :files override at all? No override — the default set already includes sources and excludes tests. Add an explicit :files that reaches those sources and excludes generated files. Extend :files to include the doc globs; keep them minimal. Exclude it explicitly so it never ships. </decision_tree>

<related_skills> Emacs Lisp language, package.el, and editor-integration foundations Macro-heavy source that must still satisfy package-lint prefix and docstring checks README, Commentary, and changelog wording during the pre-acceptance window Fetch current package-lint / package.el documentation when a check is ambiguous </related_skills>

<related_agents> Review package headers, docstrings, and lint findings against this guidance Locate shipped-vs-generated files and recipe/Makefile drift across the repo Align README/changelog availability claims with actual acceptance state </related_agents>

melpa-packaging