|
Here are some notes about updating Fuego, and some tips for when it mightbe necessary and when not.
|
{{TableOfContents}}Here are some notes about updating Fuego, and some tips for when it mightbe necessary and when not.
|
|
|
= Introduction =Fuego consists of two repositories - 'fuego' and 'fuego-core'. The contentsof the 'fuego' repository are primarily focused on the creation and managementof the docker container, and the 'fuego' Linux distribution inside it, and on global configuration for the Fuego system(including fuego configuration, board definitions and toolchains).
|
|
The 'fuego-core' repository has the core engine of Fuego, including the 'ftc'command, the core scripts, and the Fuego tests themselves (including sourcecode in many cases). This repository may get updates more frequently astests are added or as the core framework of Fuego is fixes, extended andenhanced.
|
The 'fuego-core' repository has the core engine of Fuego, including the 'ftc'command, the core scripts, and the Fuego tests themselves (including sourcecode in many cases). This repository may get updates more frequently astests are added or as the core framework of Fuego is fixes, extended andenhanced.
|
|
One of the goals of having separate repositories (which are a bit of a painto keep synchronized) is to make it possible to update the test framework and tests in 'fuego-core' without having to update the 'fuego' repository or rebuild the docker container.
|
One of the goals of having separate repositories (which are a bit of a painto keep synchronized) is to make it possible to update the test framework and tests in 'fuego-core' without having to update the 'fuego' repository or rebuild the docker container.
|
|
|
= Upgrading Fuego === 'pull'ing fuego-core ==In many cases, you can upgrade the Fuego test framework merely by doinga 'git pull' on the 'fuego-core' repository, on your host machine. Thiswill pull new features and new tests into your 'fuego-core' repository.The new scripts, tools and tests in this repository will become visible inside your container under the directory: /fuego-core.
|
|
You can even do this while the docker container is running. However,you should not do a 'git pull' on 'fuego-core' while a test is running.That might change the scripts and tools in the middle of a test, which wouldlead to unpredictable behavior.
|
You can even do this while the docker container is running. However,you should not do a 'git pull' on 'fuego-core' while a test is running.That might change the scripts and tools in the middle of a test, which wouldlead to unpredictable behavior.
|
|
If you have local modifications to existing tests, you may need to'git stash' those modifications, and merge them with the new code,in order to proceed with the update. New tests that you have createdshould be in their own directories, and should not be affected by a'git pull'.
|
If you have local modifications to existing tests, you may need to'git stash' those modifications, and merge them with the new code,in order to proceed with the update. New tests that you have createdshould be in their own directories, and should not be affected by a'git pull'.
|
|
For Fuego releases, we strive to preserve backwards compatibility withcore APIs, so that existing tests will not break when a new core frameworkis installed. However, in some rare cases this is unavoidable. Thesesituations will be noted in the release notes for a particular release.See Releases for links to information about each release.In particular, a large amount of framework refactoring occurred in the1.1 and 1.2 releases.
|
For Fuego releases, we strive to preserve backwards compatibility withcore APIs, so that existing tests will not break when a new core frameworkis installed. However, in some rare cases this is unavoidable. Thesesituations will be noted in the release notes for a particular release.See [[Releases]] for links to information about each release.In particular, a large amount of framework refactoring occurred in the1.1 and 1.2 releases.
|
|
In rare cases, which will be announced on the Fuego mailing list andnoted in the release notes, a change will be made in the framework thatis incompatible with the current format of nodes, jobs or builds, asheld by the Jenkins server. In this case it becomes impossible to usepre-existing test data with the new framework, and it may become necessaryto shelve that data and start a new instance (either of the docker containeror of Jenkins).
|
In rare cases, which will be announced on the Fuego mailing list andnoted in the release notes, a change will be made in the framework thatis incompatible with the current format of nodes, jobs or builds, asheld by the Jenkins server. In this case it becomes impossible to usepre-existing test data with the new framework, and it may become necessaryto shelve that data and start a new instance (either of the docker containeror of Jenkins).
|
|
|
== 'pull'ing fuego ==As new features are added to Fuego, sometimes it becomes necessary to alterthe way the docker container is built, or to add additional Debian packagesto the 'fuego' distribtion of Linux that is inside the container.These types of changes sometimes require that a new container be built withthe new attributes. However, building a new container eliminates the Jenkinsnode, job, and build data that is in the current container. For this reason,it is desirable to avoid rebuilding the container, if possible.
|
|
In many cases it is possible to pull a new 'fuego' repository and NOT haveto rebuild the container, by just implementing manually whatever was changed.For example, the most common change to 'fuego' is in the Dockerfile, to adda new package to the fuego distribution of Linux inside the container.While you could rebuild the container from scratch after such a change, youcan also manually just do an 'apt-get install <new-package>' inside therunning docker container. This will provide the same functionality for yourexisting docker container that a new one would have (providing that newlibrary, tool or feature).
|
In many cases it is possible to pull a new 'fuego' repository and NOT haveto rebuild the container, by just implementing manually whatever was changed.For example, the most common change to 'fuego' is in the Dockerfile, to adda new package to the fuego distribution of Linux inside the container.While you could rebuild the container from scratch after such a change, youcan also manually just do an 'apt-get install <new-package>' inside therunning docker container. This will provide the same functionality for yourexisting docker container that a new one would have (providing that newlibrary, tool or feature).
|
|
In some cases, it is possible to implement other changes as well. For example,if a tool is placed in a new location by an updated Dockerfile, then you couldmanually move the tool in your docker container, for the same effect.The details of this operation depend on what has changed. You can doa 'git log' in the 'fuego' repository for details about the changes made,and decide if you can effect those changes in your existing container, withouthaving to rebuild a new one. If you have any questions, please ask themon the Fuego mailing list, and we will try to assist.
|
In some cases, it is possible to implement other changes as well. For example,if a tool is placed in a new location by an updated Dockerfile, then you couldmanually move the tool in your docker container, for the same effect.The details of this operation depend on what has changed. You can doa 'git log' in the 'fuego' repository for details about the changes made,and decide if you can effect those changes in your existing container, withouthaving to rebuild a new one. If you have any questions, please ask themon the Fuego mailing list, and we will try to assist.
|
|
|
== preserving old containers ==Please note that you do not have to destroy or remove acontainer when you create a new one. By convention the fuego docker image is called 'fuego' and the fuego docker container is called 'fuego-container'.You can specify different names when you create a new image and container,but the preferred method of dealing with this is to rename the existingimage and container, and create new ones with the default names.If you plan to preserve an image and container, you need to preservethe 'fuego' and 'fuego-core' repositories in their same directories,or docker will get confused. That is, if you want to upgrade and createa new docker container, while still preserving the old container, youshould 'git clone' the repositories to a new directory location in yourhost filesystem. Note in this case, that you should not have boththe new container and the old container running at the same time, as therewill be conflicts over TCP port numbers and other host resources. The old testdata (from the other container) will not be visible along with any newdata in the new container (ie in the Jenkins interface). Howeverthis does provide a mechanism to preserve your data from previous tests.
|
|
Note that Fuego 'run' data is outside of the Jenkins directory, and storedon the host filesystem in fuego-rw/logs, so this data is always availableeven when the docker container is rebuilt. You should be careful, however,as Jenkins job IDs will be reused, starting from 1, for any new jobs executedwith a fresh container and instance of Jenkins. These may overwrite theresult directories from previous runs, if you re-use the same fuego/fuego-rwdirectory. This is yet another reason to use new repository directoriesfor a new docker container build (and Fuego instance).
|
Note that Fuego 'run' data is outside of the Jenkins directory, and storedon the host filesystem in fuego-rw/logs, so this data is always availableeven when the docker container is rebuilt. You should be careful, however,as Jenkins job IDs will be reused, starting from 1, for any new jobs executedwith a fresh container and instance of Jenkins. These may overwrite theresult directories from previous runs, if you re-use the same fuego/fuego-rwdirectory. This is yet another reason to use new repository directoriesfor a new docker container build (and Fuego instance).
|
|
|
= Fuego versions =Please note that this discussion applies more generally to major Fuego releases. For Fuego, and majorrelease is considered one where the second digit of the version numberis the same (the '1' or '2' in 1.1 and 1.2).
|
|
If an API-incompatible change occurs within a major release, thisis considered a regression and we will try to fix it.
|
If an API-incompatible change occurs within a major release, thisis considered a regression and we will try to fix it.
|
|
Our hope is that Fuego is starting to settle down a bit in the 1.2 release,and that API-incompatible changes will be more rare after that release.
|
Our hope is that Fuego is starting to settle down a bit in the 1.2 release,and that API-incompatible changes will be more rare after that release.
|