consul/nairobi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update instructions to upgrade Consul Democracy

Browse Source 
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.
This commit is contained in:
Javi Martín
2025-03-03 15:32:18 +01:00
parent f1f3724365
commit 10a86fd5a4
2 changed files with 110 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/en/getting_started/update.md
View File

@@ -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 <version_tag_you_are_upgrading_to>
```
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 <version_tag_you_are_upgrading_to>
```
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 '<version_tag_you_are_upgrading_to>' 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: <https://github.com/your_org_name/consuldemocracy/compare/master...consuldemocracy:master>.
## 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.