Technical Documentation
Return to Main Documentation
ENGLISH - version 2.3
ENGLISH - version 2.3
  • Introduction
  • Getting started
    • Create your fork
    • Configure your fork
    • Keep your fork updated
    • Communication
  • Installation
    • Local installation
      • Prerequisites
      • Ubuntu Linux
      • Debian Linux
      • macOS
      • Windows
      • Vagrant
      • Docker
    • Production and staging servers
      • Installer
      • Create a deploy user
      • Generating SSH Key
      • Manual installation (not recommended)
      • Digital Ocean
      • Heroku
      • Mail server configuration
    • Basic configuration
    • User documentation and guides
  • Customization
    • Introduction
    • Translations and texts
    • Images
    • Styles with CSS
    • JavaScript
    • Models
    • Controllers
    • Views and HTML
    • Components
    • Other Ruby classes (GraphQL, lib, mailers, builders)
    • Gems
    • Application configuration
    • Routes
    • Tests
  • Technical Features
    • OAuth
    • GraphQL
    • Debates and proposals recommendations
    • Configure Census Connection
    • Local Census
    • Multitenancy
    • User content translations
  • Open Source project
    • Code of conduct
    • Contributing
    • Coding conventions
    • Open source forks and modifications
    • License
Powered by GitBook
On this page
  • Preliminary steps
  • Running your test suite
  • Configuring your git remotes
  • Pulling changes from Consul Democracy
  • Merging changes
  • Making sure everything works
  • Finishing the process
  1. Getting started

Keep your fork updated

PreviousConfigure your forkNextCommunication

Last updated 1 month ago

Preliminary steps

Running your test suite

Before upgrading to a newer version of Consul Democracy, make sure you've 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 section and cloned it locally, run:

git remote -v

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, add Consul Democracy's GitHub as upstream remote with:

git remote add upstream git@github.com:consuldemocracy/consuldemocracy.git

Check it's been correctly configured by once again running:

git remote -v

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) upstream git@github.com:consuldemocracy/consuldemocracy.git (fetch) upstream git@github.com:consuldemocracy/consuldemocracy.git (push)

Pulling changes from Consul Democracy

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.

To upgrade, start by creating a branch named release from your master branch to apply the changes in the new version of Consul Democracy:

git checkout master
git pull
git checkout -b release
git fetch upstream tag <version_tag_you_are_upgrading_to>

Now you're ready to merge the changes in the new version.

Merging changes

Run:

git merge <version_tag_you_are_upgrading_to>

After running this command, there are two possible outcomes:

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.

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.

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:

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.

When upgrading to a newer version, make sure you read the of that version before upgrading.

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 ; 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).

Finally, you might want to manually check your custom code. For example, if you've or , check whether the original ERB files have changed and whether you should update your custom files in order to include those changes.

We'd love to hear about your experience! You can use the 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.

configured your fork
Create your fork
release notes
using custom folders and files for your custom changes
customized components
views
discussions about releases