Difference between revisions of "Upgrading packages"

From Openembedded.org
Jump to: navigation, search
(New page: Do you know about the powers of [http://monotone.ca/docs/Workspace.html#index-mtn-_005b_002d_002dbookkeep_002donly_005d-rename-_0040var_007bsrc_007d-_0040var_007bdst_007d-22 <u>mtn mv</u...)
 
m (Fix versioning policy link)
 
(26 intermediate revisions by 9 users not shown)
Line 1: Line 1:
+
= General upgrading procedures =
Do you know about the powers of [http://monotone.ca/docs/Workspace.html#index-mtn-_005b_002d_002dbookkeep_002donly_005d-rename-_0040var_007bsrc_007d-_0040var_007bdst_007d-22 <u>mtn mv</u>]?  If you are upgrading a package you really should. 
 
  
Please follow these steps when upgrading a package to a more recent version. This is not to be seen as dogma, but rather as best practice.  There are basically two cases we need to consider; a) you do want to keep the version of the bb file that is in OE now (somebody else needs this particular version) or b) you don't.
+
Different layers have different policies for keeping versions of software around. OE-Core for example is fairly agressive about having one, good, recent version of the software than many older versions. Other layers may have different policies.
  
= You do not need to keep the last version of the package =
+
There are two cases we need to consider:
  
# Use "[http://monotone.ca/docs/Workspace.html#index-mtn-_005b_002d_002dbookkeep_002donly_005d-rename-_0040var_007bsrc_007d-_0040var_007bdst_007d-22 <u>mtn mv</u>] packages/$pkg/$file_v1.bb packages/$pkg/$file_v2.bb" so that we don't accumulate unecessary cruft.  Using the [http://monotone.ca/docs/Workspace.html#index-mtn-_005b_002d_002dbookkeep_002donly_005d-rename-_0040var_007bsrc_007d-_0040var_007bdst_007d-22 monotone built-in rename function] also ensures we can trace the changes for a package with "mtn log" even across upgrades.
+
# You do want to keep the version of the bb file that is in OE now (somebody else needs this particular version)
# make <u>further changes</u> to packages/$pkg/$file_v2.bb as appropriate
+
# You don't.
# At the very minimum do a <u>compilation test</u> "bitbake $file" to make sure the new package does at least fetch and compile
 
# inspect the output of "<u>mtn diff</u> packages/$pkg/|less".  Is this really what you want to commit?
 
# Final step, <u>publish your work</u>. "mtn commit packages/$pkg/ && mtn pull && mtn merge && mtn push"
 
  
= You do want to keep the last version of the package =
+
== If you do not need to keep the last version of the package ==
  
Same as above, except that between the first and second step you do
+
# Use <code>git mv recipes-xyz/recipename/recipename_1.0.bb recipes-xyz/recipename/recipename_2.0.bb</code>
 +
# Make further changes to <code>recipes-xyz/recipename/recipename_2.0.bb</code> as appropriate.
 +
# At the very minimum do a compilation test (<code>bitbake recipename</code>) to make sure the new package does at least fetch and compile.
 +
# Consider using buildhistory to check for changes between the versions. See [http://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html#maintaining-build-output-quality Maintaining Build Output Quality] in the Yocto Project Reference Manual.
 +
# Inspect the output of "git diff recipes-xyz/recipename/".  Is this really what you want to commit?
 +
# Final step - publish your work. See '''[[How to submit a patch to OpenEmbedded]]'''
  
cp packages/$pkg/$file_v2.bb packages/$pkg/$file_v1.bb
+
== If you do want to keep the last version of the package ==
mtn add packages/$pkg/$file_v1.bb
 
  
Now, you may ask "Why rename the file first and then copy it back?" Good question!  With using "mtn mv" to rename and then copying back we keep the "mtn log"-history foreverJust "cp $a $b;mtn add $b" means we have a truncated history once $a gets removed.
+
Same as above, except instead of the first step:
 +
 
 +
  cp recipes-xyz/recipename/recipename_1.0.bb recipes-xyz/recipename/recipename_2.0.bb
 +
  git add recipes-xyz/recipename/recipename_2.0.bb
 +
 
 +
= Guidelines =
 +
 
 +
* If it is present, remove any line setting PR on upgrades (when PV changes).
 +
* Generally we try to avoid pre-release versions; however sometimes upstream doesn't give us a choice. See [[Versioning Policy]] for how to deal with pre-release versions.
 +
* If LIC_FILES_CHKSUM needs to be changed as part of the upgrade, you '''must''' explain exactly why in the commit message. It's fine if it is just a copyright year, formatting or other minor change; however if the license text has changed in more substantially than that it may be that the license is now materially different.
 +
 
 +
[[Category:Policy]]

Latest revision as of 13:24, 5 June 2014

General upgrading procedures

Different layers have different policies for keeping versions of software around. OE-Core for example is fairly agressive about having one, good, recent version of the software than many older versions. Other layers may have different policies.

There are two cases we need to consider:

  1. You do want to keep the version of the bb file that is in OE now (somebody else needs this particular version)
  2. You don't.

If you do not need to keep the last version of the package

  1. Use git mv recipes-xyz/recipename/recipename_1.0.bb recipes-xyz/recipename/recipename_2.0.bb
  2. Make further changes to recipes-xyz/recipename/recipename_2.0.bb as appropriate.
  3. At the very minimum do a compilation test (bitbake recipename) to make sure the new package does at least fetch and compile.
  4. Consider using buildhistory to check for changes between the versions. See Maintaining Build Output Quality in the Yocto Project Reference Manual.
  5. Inspect the output of "git diff recipes-xyz/recipename/". Is this really what you want to commit?
  6. Final step - publish your work. See How to submit a patch to OpenEmbedded

If you do want to keep the last version of the package

Same as above, except instead of the first step:

cp recipes-xyz/recipename/recipename_1.0.bb recipes-xyz/recipename/recipename_2.0.bb
git add recipes-xyz/recipename/recipename_2.0.bb

Guidelines

  • If it is present, remove any line setting PR on upgrades (when PV changes).
  • Generally we try to avoid pre-release versions; however sometimes upstream doesn't give us a choice. See Versioning Policy for how to deal with pre-release versions.
  • If LIC_FILES_CHKSUM needs to be changed as part of the upgrade, you must explain exactly why in the commit message. It's fine if it is just a copyright year, formatting or other minor change; however if the license text has changed in more substantially than that it may be that the license is now materially different.