From 10a86fd5a4b427f6036d0981cd487c9f3f06d6cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javi=20Mart=C3=ADn?= Date: Mon, 3 Mar 2025 15:32:18 +0100 Subject: [PATCH] Update instructions to upgrade Consul Democracy We now strongly recommend to upgrade one version at a time and to run the tests before and after upgrading. Note we use a `release` branch instead of an `upgrade` branch because we've been mentioning the `release` branch in the release notes of every release for years. --- docs/en/getting_started/update.md | 80 +++++++++++++++++++++---------- docs/es/getting_started/update.md | 80 +++++++++++++++++++++---------- 2 files changed, 110 insertions(+), 50 deletions(-) diff --git a/docs/en/getting_started/update.md b/docs/en/getting_started/update.md index f78e801c3..c1e2720e1 100644 --- a/docs/en/getting_started/update.md +++ b/docs/en/getting_started/update.md @@ -1,31 +1,39 @@ # Keeping your fork updated -## Configuring your git remotes +## Preliminary steps -If you created your fork correctly and cloned it locally, running: +### Running your test suite + +Before upgrading to a newer version of Consul Democracy, make sure you've [configured your fork](configuration.md) to run the tests, and that all the tests in your test suite pass. If you omit this step, it'll be much harder to upgrade since it'll be very tricky to know whether some features are broken after the upgrade. + +Please take as much time as necessary for this; every hour you spend making sure your test suite is in good shape will save countless hours of fixing bugs that made it to production. + +### Configuring your git remotes + +If you created your fork following the instructions in the [Create your fork](create.md) section and cloned it locally, run: ```bash git remote -v ``` -it should output something alike: +You should get something like: > origin git@github.com:your_user_name/consuldemocracy.git (fetch)\ > origin git@github.com:your_user_name/consuldemocracy.git (push) -Now we have to add Consul Democracy's github as upstream remote with: +Now, add Consul Democracy's GitHub as upstream remote with: ```bash git remote add upstream git@github.com:consuldemocracy/consuldemocracy.git ``` -and to check everything is fine with +Check it's been correctly configured by once again running: ```bash git remote -v ``` -again you should get: +This time you should get something like: > origin git@github.com:your_user_name/consuldemocracy.git (fetch)\ > origin git@github.com:your_user_name/consuldemocracy.git (push)\ @@ -34,36 +42,58 @@ again you should get: ## Pulling changes from Consul Democracy -Start by creating a branch named **upgrade** from your **master** branch to apply Consul Democracy changes: +When upgrading Consul Democracy, **it is extremely important that you upgrade one version at a time**. Some versions require running certain tasks that modify existing content in the database in order to make it compatible with future versions. Upgrading two versions at the same time could result in irreversible data loss. + +When we say "one version at a time", we're excluding patch versions. For example, if you're currently using version 1.2.0 and you'd like to upgrade to version 2.2.2, first upgrade to version 1.3.1, then to 1.4.1, then to 1.5.0, then to 2.0.1, then to 2.1.1 and then to version 2.2.2. That is, always upgrade to the latest patch version of a certain major/minor version. + +When upgrading to a newer version, make sure you read the [release notes](https://github.com/consuldemocracy/consuldemocracy/releases) of that version **before** upgrading. + +To upgrade, start by creating a branch named `release` from your `master` branch to apply the changes in the new version of Consul Democracy: ```bash git checkout master git pull -git checkout -b upgrade +git checkout -b release +git fetch upstream tag ``` -Then we can fetch all changes from the **Consul Democracy** remote server with: - -```bash -git fetch upstream -``` - -And then you can choose to either: - -A. Get all the latest changes on Consul Democracy's **master** branch with `git merge upstream/master`. - -B. Just update up to an specific release tag (so you can do incremental updates if you're more than one release behind). For example to update up to [1.3.0](https://github.com/consuldemocracy/consuldemocracy/releases/tag/1.3.0) release just: `git merge 1.3.0`. +Now you're ready to merge the changes in the new version. ## Merging changes -After the previous section `merge` command, there are three possible outcomes: +Run: -A. You get a nice `Already up-to-date.` response. That means your fork is up to date with Consul Democracy 馃槉馃憣. +```bash +git merge +``` -B. You get a screen on your git configured editor showing the commit message `Merge remote-tracking branch 'upstream/master' into upgrade`. That means git was able to grab latest changes from Consul Democracy's master branch, and it can merge them without code change conflicts. Finish the commit. +After running this command, there are two possible outcomes: -C. You get some git errors along with a `Automatic merge failed; fix conflicts and then commit the result.` message. That means there are conflicts between the code changes you did and the ones done on Consul Democracy repository since the last time you update it. That's the main reason we strongly recommend often updates of your fork (think at least monthly). Resolve merge conflicts carefully and commit them. +A. You get a screen on your git configured editor showing the commit message `Merge tag '' into release`. That means git was able to apply the changes in the new version and can merge them without conflicts. Finish the commit. -Now you can just simply push your **upgrade** branch to github and create a Pull Request so you can easily check all changes going into your repo, and see your tests suite runs. +B. You get some git errors along with a `Automatic merge failed; fix conflicts and then commit the result` message. That means there are conflicts between your custom code changes and the changes in the new version of Consul Democracy. That's the main reason we strongly recommend [using custom folders and files for your custom changes](../customization/introduction.md); the more you use custom folders and files, the less conflicts you will get. Resolve the merge conflicts carefully and commit them, making sure you document how you solved the conflicts (for example, in the commit message). -Remember you can always quickly check changes that will come from Consul Democracy to your fork by replacing **your_org_name** on the url: . +## Making sure everything works + +We now recommend pushing your `release` branch to GitHub (or GitLab, if that's what you usually use) and create a pull request so you can check whether your test suite reports any issues. + +It's possible that the test suite does indeed report some issues because your custom code might not correctly work with the newer version of Consul Democracy. It is **essential** that you fix all these issues before continuing. + +Finally, you might want to manually check your custom code. For example, if you've [customized components](../customization/components.md) or [views](../customization/views.md), check whether the original ERB files have changed and whether you should update your custom files in order to include those changes. + +## Finishing the process + +After making sure everything works as expected, you can either merge the pull request on GitHub/GitLab or finish the process manually: + +```bash +git checkout master +git merge release +git branch -d release +git push +``` + +Finally, read the release notes once again to make sure everything is under control, deploy to production, execute `bin/rake consul:execute_release_tasks RAILS_ENV=production` on the production server, and check everything is working properly. + +Congratulations! You've upgraded to a more recent version of Consul Democracy. Your version of Consul Democracy is now less likely to have security vulnerabilities or become an impossible-to-maintain abandonware. Not only that, but this experience will make it easier for you to upgrade to a new version in the future. + +We'd love to hear about your experience! You can use the [discussions about releases](https://github.com/consuldemocracy/consuldemocracy/discussions/categories/releases) for that (note that there are no discussions for versions prior to 2.2.0; if you've upgraded to an earlier version, please open a new discussion). This way, we'll manage to make it easier for you and everyone else to upgrade Consul Democracy next time. diff --git a/docs/es/getting_started/update.md b/docs/es/getting_started/update.md index fad60a90d..7a538f4ee 100644 --- a/docs/es/getting_started/update.md +++ b/docs/es/getting_started/update.md @@ -1,31 +1,39 @@ # Mant茅n tu fork actualizado -## Configura tus servidores remotos de git +## Pasos previos -Si creaste correctamente tu fork y lo clonaste localmente, usando: +### Ejecuta los tests + +Antes de actualizar a una versi贸n m谩s reciente de Consul Democracy, aseg煤rate de que has [configurado tu fork](configuration.md) para que ejecute los tests, y que todos los tests pasan. Si te saltas este paso, ser谩 mucho m谩s dif铆cil actualizar ya que no habr谩 una manera fiable de comprobar si alguna funcionalidad se ha roto tras la actualizaci贸n. + +Dedica a este paso tanto tiempo como necesites; por cada hora que pases asegur谩ndote de que tus tests funcionan correctamente te ahorrar谩s numerosas horas de arreglar fallos que llegaron a producci贸n. + +### Configura tus servidores remotos de git + +Si creaste tu fork siguiendo las instrucciones de la secci贸n [Crea tu fork](create.md) y lo clonaste en tu m谩quina, ejecuta: ```bash git remote -v ``` -deber铆as ver algo como: +Deber铆as ver algo como: > origin git@github.com:your_user_name/consuldemocracy.git (fetch)\ > origin git@github.com:your_user_name/consuldemocracy.git (push) -Ahora debes a帽adir el repositorio git de Consul Democracy como servidor remoto con: +Ahora a帽ade el repositorio git de Consul Democracy como servidor remoto con: ```bash git remote add upstream git@github.com:consuldemocracy/consuldemocracy.git ``` -comprueba de nuevo que con: +Comprueba que se ha configurado correctamente ejecutando nuevamente: ```bash git remote -v ``` -deber铆as ver algo como: +Esta vez deber铆as ver algo como: > origin git@github.com:your_user_name/consuldemocracy.git (fetch)\ > origin git@github.com:your_user_name/consuldemocracy.git (push)\ @@ -34,36 +42,58 @@ deber铆as ver algo como: ## Obteniendo cambios de Consul Democracy -Empieza creando una rama **upgrade** a partir de tu rama **master** sobre la que trabajar: +Cuando actualices Consul Democracy, **es muy importante que actualices las versiones de una en una**. Algunas versiones requieren ejecutar tareas que modifican contenido de la base de datos para que este contenido sea compatible con futuras versiones. Actualizar dos versiones de golpe podr铆a resultar en una p茅rdida irreversible de datos. + +Cuando decimos "de una en una", no tenemos en cuenta las versiones de mantenimiento (en ingl茅s, "patch"). Por ejemplo, si est谩s usando la versi贸n 1.2.0 y quieres actualizar a la versi贸n 2.2.2, actualiza primero a la versi贸n 1.3.1, luego la 1.4.1, luego a la 1.5.0, luego a la 2.0.1, luego a la 2.1.1 y finalmente a la 2.2.2. Esto es, actualiza siempre a la 煤ltima versi贸n "patch" de una versi贸n mayor/menor. + +Al actualizar a una versi贸n, lee las [notas de versi贸n](https://github.com/consuldemocracy/consuldemocracy/releases) de dicha versi贸n **antes** de actualizar. + +Para actualizar, empieza creando una rama `release` a partir de tu rama `master`: ```bash git checkout master git pull -git checkout -b upgrade +git checkout -b release +git fetch upstream tag ``` -Y actualiza la informaci贸n del repositorio de **Consul Democracy** con las referencias a las ramas, tags, etc..: - -```bash -git fetch upstream -``` - -Y por fin puedes elegir entre: - -A. Actualizar con los 煤ltimos cambios de la rama **master** usando `git merge upstream/master` - -B. S贸lo actualizar hasta cierta versi贸n (en el caso de que prefieras actualizar de forma incremental, si est谩s varias versiones por detr谩s). Por ejemplo para actualizarte a la versi贸n [1.3.0](https://github.com/consuldemocracy/consuldemocracy/releases/tag/1.3.0) utilizamos el tag asociado: `git merge 1.3.0` +Ahora est谩s listo para fusionar los cambios de la nueva versi贸n. ## Fusionando cambios -Tras el `merge` de la anterior secci贸n, hay tres posibles escenarios: +Ejecuta: -A. Obtienes una respuesta `Already up-to-date.`. Eso significa que tu fork esta al d铆a con los cambios de Consul Democracy 馃槉馃憣 +```bash +git merge +``` -B. Se abre una ventana del editor que tengas configurado en git, mostrando el mensaje de commit `Merge remote-tracking branch 'upstream/master' into upgrade`. Esto significa que git fue capaz de mezclar los cambios de Consul Democracy sobre tu c贸digo sin encontrar problemas o conflictos. Termina el commit. +Tras ejecutar esta orden, hay dos posibles escenarios: -C. Recibes mensajes de error de git junto con un `Automatic merge failed; fix conflicts and then commit the result.`. Esto significa que se han encontrado conflictos entre los cambios en tu c贸digo y los cambios que se realizaron en Consul Democracy desde la 煤ltima vez que actualizaste tu fork. Esta es una de las principales razones para intentar mantener tu fork lo m谩s al d铆a posible, realizando este proceso al menos mensualmente. Resuelve manualmente los conflictos para terminar el merge y haz un commit. +A. Se abre una ventana del editor que tengas configurado en git, mostrando el mensaje de commit `Merge '' into release`. Esto significa que git fue capaz de mezclar los cambios de la nueva versi贸n de Consul Democracy sobre tu c贸digo sin encontrar conflictos. Termina el commit. -Ahora simplemente sube la rama **upgrade** a github y crea un Pull Request. As铆 podr谩s ver de manera sencilla todos los cambios que se han realizado en el repositorio y ver谩s tambi茅n c贸mo arranca la suite de tests. +B. Recibes mensajes de error de git junto con un `Automatic merge failed; fix conflicts and then commit the result`. Esto significa que se han encontrado conflictos entre los cambios en tu c贸digo y los cambios en la nueva versi贸n de Consul Democracy. Esta es una de las principales razones por las que recomendamos [usar los directorios y archivos "custom" para tus cambios](../customization/introduction.md); cuanto m谩s uses los directorios y archivos "custom", menos conflictos tendr谩s. Resuelve manualmente los conflictos para terminar el merge y haz un commit, documentando c贸mo resolviste los conflictos (por ejemplo, en el mensaje de commit). -Recuerda que siempre puedes comprobar r谩pidamente los cambios que tienes pendientes de integrar de Consul Democracy a tu fork sustituyendo **your_org_name** en la url: +## Comprueba que todo funciona + +Ahora, te recomendamos que subas los cambios en tu rama `release` a GitHub (o GitLab, si es lo que usas normalmente) y abras una "Pull Request" para comprobar si todos los tests funcionan correctamente. + +Es posible que al ejecutar los tests veas que algunos fallen porque los cambios que has hecho en el c贸digo no sean compatibles con la nueva versi贸n de Consul Democracy. Es **esencial** que arregles estos fallos antes de seguir adelante. + +Por 煤ltimo, vendr铆a bien que comprobases manualmente tu c贸digo. Por ejemplo, si has [personalizado componentes](../customization/components.md) o [vistas](../customization/views.md), comprueba si los archivos ERB originales han cambiado y, en caso afirmativo, si deber铆as actualizar tus archivos personalizados para incluir estos cambios. + +## Pasos finales + +Una vez comprobado que todo funciona, puedes incluir los cambios de la "Pull Request" en tu rama `master` utilizando la interfaz de GitHub/GitLab o terminar el proceso manualmente: + +```bash +git checkout master +git merge release +git branch -d release +git push +``` + +Por 煤ltimo, lee las notas de versi贸n una vez m谩s para asegurarte de que todo est谩 bajo control, sube estos cambios a producci贸n, ejecuta `bin/rake consul:execute_release_tasks RAILS_ENV=production` en el servidor de producci贸n, y comprueba que todo funciona como deber铆a. + +隆Enhorabuena! Has actualizado a una versi贸n m谩s reciente de Consul Democracy. Tu versi贸n de Consul Democracy es ahora m谩s resistente a posibles problemas de seguridad y tiene un menor peligro de quedar abandonada por ser imposible de mantener. No solo eso, sino que esta experiencia har谩 que te sea m谩s f谩cil actualizar a una nueva versi贸n en el futuro. + +隆Nos encantar铆a escuchar c贸mo te ha ido! Para esto, puedes usar las [conversaciones sobre nuevas versiones](https://github.com/consuldemocracy/consuldemocracy/discussions/categories/releases) (ten en cuenta que no hay conversaciones para versiones anteriores a la 2.2.0; si has actualizado a una versi贸n anterior, abre una nueva conversaci贸n). As铆, entre todos conseguiremos que tanto t煤 como las dem谩s personas que usan Consul Democracy puedan actualizar m谩s f谩cilmente la pr贸xima vez.