Vida del proyecto: issues, contribuciones, CI y el coste de mantener

Publicar un plugin es rápido. Lo que empieza ese día es otra cosa: una relación de duración indefinida con desconocidos que dependen de tu tiempo libre. Llegarán issues escritos en dos líneas desde configuraciones que combinan cuarenta plugins, contribuciones bienintencionadas que doblan la superficie de la API, peticiones razonables que no puedes atender y agradecimientos que llegan justo cuando ibas a abandonar. Nada de eso es un problema técnico, y sin embargo es lo que decide si el proyecto sigue vivo dentro de dos años. Esta última lección trata de construir las estructuras que hacen sostenible esa relación, y de mirar de frente su coste real antes de contraerlo.

El issue como unidad de trabajo

Un issue útil contiene tres cosas: qué esperabas, qué pasó y cómo reproducirlo desde cero. La tercera es la que falta siempre, y sin ella la conversación se convierte en una investigación por correspondencia que consume más tiempo que arreglar el fallo. La solución no es pedirla con más énfasis, es hacerla trivial: se distribuye un archivo de configuración mínima que instala solo tu plugin y sus dependencias, y se pide que el fallo se reproduzca con él.

-- repro.lua : ejecutar con  nvim --clean -u repro.lua
local raiz = vim.fn.stdpath("run") .. "/mi-plugin-repro"
for _, sub in ipairs({ "data", "state", "cache", "config" }) do
  vim.env[("XDG_%s_HOME"):format(sub:upper())] = raiz .. "/" .. sub
end

local lazy = raiz .. "/data/nvim/lazy/lazy.nvim"
if not vim.uv.fs_stat(lazy) then
  vim.fn.system({ "git", "clone", "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git", lazy })
end
vim.opt.runtimepath:prepend(lazy)

require("lazy").setup({
  { "autor/mi-plugin", opts = {} },
}, { root = raiz .. "/data/nvim/lazy" })

Ese archivo hace dos cosas a la vez, y la segunda importa más que la primera. Resuelve técnicamente el aislamiento —nada del entorno del usuario contamina la prueba—, y traslada la carga de la demostración a quien afirma, que es donde debe estar. Buena parte de los issues se cierran solos en cuanto alguien intenta reproducirlos en limpio y descubre que el conflicto estaba en otro plugin. La plantilla de issue, por su parte, no es burocracia: es un formulario con la versión de Neovim, la salida del comando de comprobación de salud y el archivo de reproducción, y su función real es evitar la primera ronda de preguntas, que es la que agota.

La otra mitad del triaje la resuelve una comprobación de salud, que es el único mecanismo que te permite recibir en el issue un diagnóstico del entorno ajeno sin tener que pedirlo pieza a pieza.

-- lua/mi-plugin/health.lua : responde a  :checkhealth mi-plugin
local M = {}

function M.check()
  vim.health.start("mi-plugin")
  if vim.fn.has("nvim-0.10") == 1 then
    vim.health.ok("version de Neovim suficiente")
  else
    vim.health.error("se requiere Neovim 0.10 o superior")
  end
  if vim.fn.executable("rg") == 1 then
    vim.health.ok("ripgrep encontrado")
  else
    vim.health.warn("ripgrep ausente", { "instalalo para la busqueda rapida" })
  end
end

return M

Media hora de trabajo, y a cambio cada issue llega con las dependencias, las versiones y la configuración efectiva ya comprobadas. Es probablemente la mejor relación entre esfuerzo y tiempo ahorrado de todo este nivel.

Contribuciones que puedes aceptar

Una contribución no es un regalo neutro: es una propuesta de que asumas el mantenimiento perpetuo de código que no escribiste. Con esa lente, aceptar deja de ser lo educado por defecto y pasa a ser una decisión con criterio, y el criterio conviene tenerlo escrito antes de que llegue la primera.

Escribir un archivo de contribución con estas reglas ahorra conversaciones incómodas, porque convierte un rechazo personal en la aplicación de una norma pública que ya existía. Debe incluir además lo aburrido y necesario: cómo ejecutar las pruebas en local, qué formateador y qué analizador estático se usan, el formato de los mensajes de commit si automatizas las notas de cambios, y la licencia bajo la que se aporta. Y hay una frase que conviene decir en voz alta y sin rodeos: no, dicho pronto y con amabilidad, es un servicio a quien contribuye. Una petición que queda abierta seis meses cuesta más disgusto que un rechazo razonado el primer día.

Integración continua que responde por ti

Todo lo que puedas verificar automáticamente es una conversación que no tendrás que mantener. Una integración continua modesta —formato, análisis estático, pruebas sobre las versiones que declaraste soportar y regeneración de la documentación— cubre la práctica totalidad de los comentarios repetitivos de una revisión.

jobs:
  pruebas:
    strategy:
      matrix:
        version: [v0.10.4, stable, nightly]
    steps:
      - uses: actions/checkout@v4
      - uses: rhysd/action-setup-vim@v1
        with:
          neovim: true
          version: ${{ matrix.version }}
      - run: make test
      - run: make lint

describe("anotaciones", function()
  it("marca la funcion actual al ejecutar el comando", function()
    local buf = vim.api.nvim_create_buf(false, true)
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, { "local function f() end" })
    vim.api.nvim_set_current_buf(buf)

    require("mi-plugin").setup({})
    vim.cmd("MiPluginAnotar")

    local ns = vim.api.nvim_create_namespace("mi-plugin")
    local marcas = vim.api.nvim_buf_get_extmarks(buf, ns, 0, -1, {})
    assert.equals(1, #marcas)
  end)
end)

Las pruebas de un plugin de Neovim se ejecutan dentro de una instancia real del editor, porque casi todo lo interesante depende de buffers, ventanas y eventos que no existen fuera. Las bibliotecas habituales arrancan una instancia hija, ejecutan las aserciones contra ella y devuelven el resultado, lo que permite probar de verdad que un comando modifica el buffer que debe. El resto de la automatización es igual de valiosa y mucho más barata: comprobar que el formateador no cambiaría nada, que el analizador estático no encuentra variables globales accidentales, y que el archivo de ayuda regenerado coincide con el versionado.

flowchart TB
iss[Issue nuevo] --> pl[Plantilla con version y salud]
pl --> rep[Reproduccion con archivo minimo]
rep --> tri[Triaje y etiqueta]
tri --> cerr[Se cierra solo: era otro plugin]
tri --> arr[Correccion con prueba de regresion]
arr --> ci[Integracion continua sobre la matriz]
ci --> tag[Publicacion y notas de cambios]
style rep fill:#cba6f7,color:#11111b
style ci fill:#a6e3a1,color:#11111b

El coste real de mantener

Conviene hacer la aritmética en vez de descubrirla. Un plugin con unos pocos miles de usuarios genera un flujo constante y modesto: algunos issues al mes, alguna contribución, un par de roturas al año provocadas por cambios del propio editor, y el trabajo periódico de publicar. Nada de eso es dramático por separado; lo que agota es que no se detiene, que llega en el momento que no eliges y que la parte que consume más tiempo no es programar sino leer, entender, responder y decidir.

Hay cuatro decisiones que reducen ese coste más que cualquier otra cosa, y todas se toman antes de necesitarlas. Declarar por escrito qué no hace el plugin, para que las peticiones fuera de alcance se resuelvan con un enlace. Mantener la superficie pequeña, porque cada símbolo público es una fuente permanente de preguntas. Automatizar sin piedad todo lo verificable. Y responder pronto aunque sea para decir que no vas a hacerlo: la deuda emocional de un issue sin contestar pesa mucho más que la de uno cerrado.

Queda la parte que casi nadie escribe y que es la más importante. Un proyecto puede terminar, y terminarlo bien es un acto de responsabilidad, no de fracaso. Archivar el repositorio con una nota honesta en el README, señalar las alternativas que existen y ofrecer el traspaso a quien quiera continuarlo deja a los usuarios en mejor posición que un proyecto formalmente vivo que lleva año y medio sin responder. Un mantenedor que se retira con claridad hace más por su comunidad que uno que desaparece en silencio.