Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Improve documentation about TLE upgrades

Abierto
  • ¿Algo no está bien?
#164 5 comentarios 1 reacción 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
28/100
Tipo de issue
Documentación
Claridad
Necesita aclaración
Estado de actividad
Estancado
Stack tecnológico
postgresql
Área
databases, documentation

Línea de trabajo

Comienza revisando las preguntas sobre las actualizaciones y el issue #158 vinculado, centrado en los usuarios; después, recopila el comportamiento existente de las actualizaciones de TLE y las directrices del proyecto. Documenta las rutas de actualización compatibles, las expectativas de seguridad de los datos, las prácticas de migración, las advertencias y los ejemplos para que tanto los autores de TLE como los usuarios puedan entender cómo deben escribirse y aplicarse las actualizaciones.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

documentation

Improve documentation

I do not see a page which addresses or explains how TLE updates are supposed to be written and applied

Describe the problem

As a developer, I cannot figure out how to safely write a new version:

  1. Do I have to assume that the users may already have a previous version installed? This means using defensive statements like "create table if not exists" and "create or replace view". What if I have multiple previous versions? Do I need to account for all of these? (this would be increasingly unmaintainable over time)
  2. What if my users have data that they have stored in tables my extension has created? How can I know the right way to migrate such data? Is there some way I can warn users before "resetting" things?
  3. What if the new version tries to modify something that is restricted? For instance, a constraint/primary key that needs modifying may have to be dropped before being recreated but cannot be done while there is data that references it. In this case, I have no way to modify the constraint other than to drop table data.

As a user, I cannot tell how to upgrade a TLE or what to expect when I do. For example:

  1. Do I have to update in sequence or can I skip versions and jump from 1.0 to 6.0 and let dbdev figure it out?
  2. Is any of my data at risk? What if the TLE created tables when I first installed it? Will those table persist or be destroyed/recreated? Is this up to the author? If so, how do I protect myself from bad updates?

Describe the improvement

I would like extensive documentation and examples of how devs are expecting to write and provide TLE updates. I would also like a list of best practices, warnings, errors, and dangers that could result from not following the guidelines. Overall this system currently feels opaque and risky for both devs and users.

Additional context

I was asked if I could provide my package as a TLE, which I did but I am now unsure how to update it. I asked a while ago but didn't get a response and now my users are asking me. I also have an update I'd like to push. This also overlaps the user-focused issue here.

Lenguaje dominante
TypeScript
Estrellas
442
Forks
31
Merge medio
1 h 22 min
PR fusionados (30 d)
9

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de supabase/dbdev

Todos los issues de supabase/dbdev

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.