From Fedora Project Wiki

(add git branching description)
(Redirect Package Maintainer wiki links to docs.fp.o)
 
(23 intermediate revisions by 3 users not shown)
Line 17: Line 17:
</pre>
</pre>


== Git branching ==


All the changes must be done in a correct git branch. The description below documents the process.
= Stable release =
The following process concerns a stable public release of AutoQA. We use this procedure when we want to officially release a new version of AutoQA for all our users.


=== Major or minor releases ===
== Switch Git branch ==
All the changes must be done in a correct git branch.


AutoQA uses ''release branches'' for every major or minor release. That means before tagging a new release a new branch is always created. If we want to create new 0.X.0 minor release:
<ul>
<li>If you want to create a new ''X.Y.0'' major or minor release, create a new ''release branch'':
<pre>git checkout -b release-X.Y master</pre>
{{admon/tip|Time of branching|It is possible to create ''release-X.Y'' branch immediately before tagging ''X.Y.0'' release, or it is possible to do it much earlier - then we can use ''master'' for further heavy development and ''release-X.Y'' for stabilization of the current features.}}</li>
<li>If you want to create a new revision release ''X.Y.Z'', switch to a corresponding existing release branch:
<pre>git checkout release-X.Y</pre>
and apply all hotfixes you have prepared.</li>
</ul>


<ol>
== Update {{filename|autoqa.spec}} and {{filename|NEWS}} ==
<li>Create new release branch: <pre>git checkout -b release-0.X master</pre></li>
Every new release must be mentioned in the rpm {{filename|spec}} file. We also want to provide high-level changes overview in the {{filename|NEWS}} file.
<li>[[#Update autoqa.spec|Update the {{filename|autoqa.spec}} file and commit]]</li>
<li>[[#Cherry-pick to master|Cherry-pick the last commit to master]]</li>
<li>Tag new release:<pre>git tag v0.X.0 release-0.X</pre></li>
<li>Push changes to remote repository:<pre>git push --tags origin master release-0.X</pre></li>
</ol>


{{admon/tip|Time of branching|It is possible to create ''release-0.X'' branch immediately before tagging ''0.X.0'' release, or it is possible to do it much earlier - then we can use ''master'' for further heavy development and ''release-0.X'' for stabilization of the current features.}}
# Edit {{filename|autoqa.spec}} by incrementing the <code>Version</code> and updating the <code>%changelog</code>
# Edit {{filename|NEWS}} file and add a section for the new release. Document only the most important end-user visible changes.
# Locally commit the changes <pre>git commit autoqa.spec NEWS</pre>


{{admon/note|Major releases|The process for major releases it's the same as described above, just replace ''branch-0.X'' names with ''branch-X.0''.}}
== Tag the release ==
The last commit (changing the {{filename|autoqa.spec}} file) must be tagged to mark the release.


=== Revision releases ===
# Tag the commit: <pre>git tag vX.Y.Z</pre>
# Check that the tag was applied to the correct commit by inspecting: <pre>git log --decorate=full</pre>


All revision releases simply mean committing relevant changesets to the relevant release branch and tagging a new release:
== Pull changes back to master ==
After you tag the release on the release branch, you need to pull the release-related changes (now tagged with ''vX.Y.Z'' tag) into the master branch. Merging is a preferred approach, because it ensures the master branch will contain the ''vX.Y.Z'' commit. But it is desirable only for a fast-forward merge, otherwise some other changes (we might not want) may be pulled in as well. In that case (e.g. the release branch was used for stabilization and contain several previous commits) we need to use cherry-picking.


<ol>
# Change to the ''master'' branch <pre>git checkout master</pre>
<li>Switch to correct release branch: <pre>git checkout release-0.X</pre></li>
# If you created the release branch immediately before tagging a new release, merge the changes using fast-forward approach: <pre>git merge --ff-only release-X.Y</pre>
<li>Commit the hotfixes you have prepared</li>
# If you can't use fast-forward merge or it failed, cherry pick the appropriate commit instead: <pre>git cherry-pick vX.Y.Z</pre>
<li>[[#Update autoqa.spec|Update the {{filename|autoqa.spec}} file and commit]]</li>
<li>Tag new release:<pre>git tag v0.X.Y</pre></li>
<li>Push changes to remote repository:<pre>git push --tags origin release-0.X</pre></li>
</ol>
 
== Intermediary tasks ==
 
=== Update {{filename|autoqa.spec}} ===
Every new release must be mentioned in the rpm {{filename|spec}} file.
 
# Edit {{filename|autoqa.spec}} by incrementing the <code>Version</code> and updating the <code>%changelog</code>
# Locally commit the changes <pre>git commit autoqa.spec</pre>


=== Cherry-pick to master ===
== Push changes to remote repository ==
After you tag the release on the release branch, you will want to cherry-pick the {{filename|autoqa.spec}} change (e.g. tagged with ''release-0.X'' tag) into the master branch.
It's time now to push all the changes to the shared remote ''origin'' repository.
 
# Change to the ''master'' branch <pre>git checkout master</pre>
# Cherry-pick the updated {{filename|autoqa.spec}} change <pre>git cherry-pick release-0.X</pre>


== Closing tasks ==
# Push the release branch changes: <pre>git push --tags origin release-X.Y</pre>
# If you modified the ''master'' branch (i.e. for major or minor releases), push it too: <pre>git push --tags origin master</pre>


=== Upload tarball ===
== Upload tarball ==
Like many projects, the appropriate method to release a new version is by tarball.  Once you have tagged the release, upload a new tarball using the following commands.
Like many projects, the appropriate method to release a new version is by tarball.  Once you have tagged the release, upload a new tarball using the following commands.


# Check-out the correct tag (e.g. ''v0.X.0'') <pre>git checkout v0.X.0</pre>
# Check-out the correct tag <pre>git checkout vX.Y.Z</pre>
# Upload a new release tarball <pre>make upload</pre>
# Upload a new release tarball <pre>make upload</pre>


=== Build a source RPM ===
== Build a source RPM ==
With the tarball uploaded, it's time to package the new release as an RPM.
With the tarball uploaded, it's time to package the new release as an RPM.


# Check-out the correct tag (e.g. ''v0.X.0'') <pre>git checkout v0.X.0</pre>
# Check-out the correct tag <pre>git checkout vX.Y.Z</pre>
# Build a source package <pre>make srpm</pre>
# Build a source package <pre>make srpm</pre>


=== Build for applicable releases ===
== Build for applicable releases ==
With a source RPM created, it's time to '''build''' updated packages for any existing ''stable'' repositories.  This includes {{FedoraVersion|long|current}}, {{FedoraVersion|long|previous}} and, depending on the time of release, potentially {{FedoraVersion|long|previous2}}.  Traditionally, this step would be handled by running the {{command|koji build --tag dist-f{{FedoraVersionNumber|current}}-updates path/to/src.rpm}} command.  However, since {{package|autoqa}} is not yet packaged and available in Fedora repositories, updates are built locally using {{command|mock}}.
With a source RPM created, it's time to '''build''' updated packages for any existing ''stable'' repositories.  This includes {{FedoraVersion|long|current}}, {{FedoraVersion|long|previous}} and, depending on the time of release, potentially {{FedoraVersion|long|previous2}}.  Traditionally, this step would be handled by running the {{command|koji build --tag dist-f{{FedoraVersionNumber|current}}-updates path/to/src.rpm}} command.  However, since {{package|autoqa}} is not yet packaged and available in Fedora repositories, updates are built locally using {{command|mock}}.


{{admon/note|Update your mock configuration|You will need to update the mock configuration files in {{filename|/etc/mock}} so that the autoqa package repositories are included. Information on autoqa package repositories is available at [[Install_and_configure_AutoQA]].}}
{{admon/note|Update your mock configuration|You will need to update the mock configuration files in {{filename|/etc/mock}} so that the autoqa package repositories are included. This means updating all mock configuration files of all systems you want to build RPMs for. For instance, if you are going to build for Fedora 16, you will add the following into {{filename|/etc/mock/fedora-16-x86_64.cfg}}
 
# Build packages using mock for Fedora, specify version using <code>RELEASEVER</code> variable {{#tag:pre|make mock-fedora RELEASEVER={{FedoraVersionNumber|current}} }}
# Repeat the build procedure for all desired releases
 
{{admon/note|Building for EPEL-5?|Due to changes in the [[Features/StrongerHashes|filedigest algorithm]], extra care is required when creating packages for [[EPEL|EPEL-5]].  Be sure to set the <code>_source_filedigest_algorithm</code> and <code>_binary_filedigest_algorithm</code> for any packages used when building for EPEL-5. For convenience, a {{filename|Makefile}} target is available to create EPEL-5 compatible packages.
<pre>
<pre>
make mock-epel RELEASEVER=5
[fedora-autoqa]
name=The autoqa project provides a basic framework for Fedora test automation
baseurl=http://repos.fedorapeople.org/repos/fedora-qa/autoqa/fedora-16/x86_64
enabled=1
skip_if_unavailable=1
gpgcheck=0
</pre>
</pre>
Information on autoqa package repositories is available at [[Install_and_configure_AutoQA]].
}}
}}


=== Create updates ===
# Build packages using mock for Fedora, specify version using <code>DIST</code> variable.  For possible values for <code>DIST</code>, consult [[Packaging:DistTag]] {{#tag:pre|make mock DIST=.fc{{FedoraVersionNumber|current}} }}
With packages built, it's time to submit them as updates.  Traditionally, this step would be handled by using the [[Package_update_HOWTO#Working_with_packages_in_the_stable_branches|bodhi update tool]].  However, since {{package|autoqa}} is not yet packaged and available in official Fedora repositories, a [[Fedorapeople_Repos|custom package repository]] is used to deliver updates.
# Repeat the build procedure for all desired releases
 
== Create updates ==
With packages built, it's time to submit them as updates.  Traditionally, this step would be handled by using the [https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide/#later_branched_and_stable_releases bodhi update tool].  However, since {{package|autoqa}} is not yet packaged and available in official Fedora repositories, a [[Fedorapeople_Repos|custom package repository]] is used to deliver updates.


<ol>
<ol>
<li> Mirror the autoqa package repository locally <pre>rsync -avz fedorapeople.org:/srv/repos/fedora-qa/autoqa ~/public_html/ ; cd autoqa/</pre></li>
<li> Mirror the autoqa package repository locally <pre>rsync -avz fedorapeople.org:/srv/repos/fedora-qa/autoqa ~/public_html/ ; cd autoqa/</pre></li>
<li> Add locally built packages to the desired repositories <pre>./move-pkgs.sh path/to/autoqa.git/rpm-build/MOCK/*/*.rpm</pre>
<li> Add locally built packages to the desired repositories <pre>./move-pkgs.sh path/to/autoqa.git/build/MOCK/*/*.rpm</pre>
{{admon/note|Simulating the ''updates-testing'' repository|For pre-release or testing packages an alternative repository is available to mimic the official ''updates-testing'' Fedora repository.  To submit packages into the ''fedora-autoqa-testing'' repository, add the command-line option <code>-r testing</code>.  A complete example is included below.
{{admon/note|Simulating the ''updates-testing'' repository|For pre-release or testing packages an alternative repository is available to mimic the official ''updates-testing'' Fedora repository.  To submit packages into the ''fedora-autoqa-testing'' repository, add the command-line option <code>-r testing</code>.  A complete example is included below.
<pre>./move-pkgs.sh -r testing path/to/autoqa.git/rpm-build/MOCK/*/*.rpm</pre>
<pre>./move-pkgs.sh -r testing path/to/autoqa.git/build/MOCK/*/*.rpm</pre>
}}</li>
}}</li>
<li> Update the yum repo metadata <pre>./update-repos.sh</pre></li>
<li> Update the yum repo metadata <pre>./update-repos.sh</pre></li>
<li> Update remote repository with changes <pre> rsync -avz ~/public_html/autoqa fedorapeople.org:/srv/repos/fedora-qa/</pre></li>
<li> Update remote repository with changes <pre> rsync -avz ~/public_html/autoqa fedorapeople.org:/srv/repos/fedora-qa/</pre></li>
<li> Change permissions on the server so that anyone in gitautoqa FAS group can update the repos<pre> chgrp -R gitautoqa /srv/repos/fedora-qa/autoqa</pre><pre> chmod g+w -R /srv/repos/fedora-qa/autoqa</pre></li>
</ol>
</ol>


Line 108: Line 107:
=== Purging old release branches ===
=== Purging old release branches ===


If we are sure we will no longer work on older releases (e.g. before ''0.X''), we can also delete older release branches. If Y < X, then we can delete ''release-0.Y'':
If we are sure we will no longer work on older releases (e.g. before ''X.Y''), we can also delete older release branches. If W < Y, then we can delete ''release-X.W'':
 
<ol>
<li>Make sure there's a tag at the tip of the branch and therefore no work is lost:
<pre>git tag --contains origin/release-X.W</pre>
This must output some tag (like ''vX.W.3''). Otherwise the branch contains commits which are not part of any tag.</li>
<li>Delete the remote branch:
<pre>git push origin :release-X.W</pre></li>
<li>Prune the local branches (that no longer exist on the remote server):
<pre>git remote prune origin</pre></li>
</ol>
 
The same goes for deleting older major branches (branches ''release-Q.Y'' where Q < X).
 


<pre>
= Testing release =
git tag --contains release-0.Y  # This must output some tag (like v0.Y.3).  
The following process concerns a testing release of AutoQA. We use this procedure when we want to deploy a testing version of AutoQA onto our staging server for thorough testing.
                                # It ensures there's a tag at the tip of  
                                # the branch and therefore no work is lost.
git branch -D release-0.Y
git push origin :release-0.Y
</pre>


== Build and install RPM ==
# SSH to the staging server and go to the AutoQA checkout directory (create one if you don't have one).
# Switch to the git branch you want to test, probably ''master'': <pre>git pull; git checkout master</pre>
# Build an RPM from current ''HEAD'' using the same approach as in [[#Build for applicable releases]], but with appending <code>DEVEL=1</code> option: <pre>make mock DEVEL=1</pre>
#* Your user must be in the ''mock'' group to be able to run this.
# Install the RPM created in {{filename|./build/MOCK/<release>/}}.
#* Since we use <code>git describe</code> to generate package versions and sometimes we build and install package from other branches than master, you can actually end up with a package version that is lower than the one currently installed. Instead of using <code>yum update autoqa-version.rpm</code> use <code>yum downgrade autoqa-version.rpm</code>.
#* Be sure to inspect all {{filename|.rpmnew}} and {{filename|.rpmold}} files (if they are created, yum will tell you so) and merge the changes.




[[Category:AutoQA]]
[[Category:AutoQA]]

Latest revision as of 17:14, 7 October 2021

This page describes the process for tagging, building and deploying a new version of autoqa. This page assumes a basic understanding of rpm spec file syntax and commands such as git, mock and yum.

Numbering scheme

Each release has X.Y.Z identification denoting a major, a minor and a revision number:

  • Major number is increased when AutoQA makes incompatible changes in its test API. (Not used currently, since no stable public API has been offered yet.)
  • Minor number is increased when AutoQA adds new features.
  • Revision number is increased when AutoQA adds new hotfixes, but no new features.

Pre-requisites

You must have AutoQA source code checked out with write access (ssh:// protocol, requires gitautoqa membership):

git clone ssh://git.fedorahosted.org/git/autoqa.git
cd autoqa


Stable release

The following process concerns a stable public release of AutoQA. We use this procedure when we want to officially release a new version of AutoQA for all our users.

Switch Git branch

All the changes must be done in a correct git branch.

  • If you want to create a new X.Y.0 major or minor release, create a new release branch:
    git checkout -b release-X.Y master
    Time of branching
    It is possible to create release-X.Y branch immediately before tagging X.Y.0 release, or it is possible to do it much earlier - then we can use master for further heavy development and release-X.Y for stabilization of the current features.
  • If you want to create a new revision release X.Y.Z, switch to a corresponding existing release branch:
    git checkout release-X.Y
    and apply all hotfixes you have prepared.

Update autoqa.spec and NEWS

Every new release must be mentioned in the rpm spec file. We also want to provide high-level changes overview in the NEWS file.

  1. Edit autoqa.spec by incrementing the Version and updating the %changelog
  2. Edit NEWS file and add a section for the new release. Document only the most important end-user visible changes.
  3. Locally commit the changes
    git commit autoqa.spec NEWS

Tag the release

The last commit (changing the autoqa.spec file) must be tagged to mark the release.

  1. Tag the commit:
    git tag vX.Y.Z
  2. Check that the tag was applied to the correct commit by inspecting:
    git log --decorate=full

Pull changes back to master

After you tag the release on the release branch, you need to pull the release-related changes (now tagged with vX.Y.Z tag) into the master branch. Merging is a preferred approach, because it ensures the master branch will contain the vX.Y.Z commit. But it is desirable only for a fast-forward merge, otherwise some other changes (we might not want) may be pulled in as well. In that case (e.g. the release branch was used for stabilization and contain several previous commits) we need to use cherry-picking.

  1. Change to the master branch
    git checkout master
  2. If you created the release branch immediately before tagging a new release, merge the changes using fast-forward approach:
    git merge --ff-only release-X.Y
  3. If you can't use fast-forward merge or it failed, cherry pick the appropriate commit instead:
    git cherry-pick vX.Y.Z

Push changes to remote repository

It's time now to push all the changes to the shared remote origin repository.

  1. Push the release branch changes:
    git push --tags origin release-X.Y
  2. If you modified the master branch (i.e. for major or minor releases), push it too:
    git push --tags origin master

Upload tarball

Like many projects, the appropriate method to release a new version is by tarball. Once you have tagged the release, upload a new tarball using the following commands.

  1. Check-out the correct tag
    git checkout vX.Y.Z
  2. Upload a new release tarball
    make upload

Build a source RPM

With the tarball uploaded, it's time to package the new release as an RPM.

  1. Check-out the correct tag
    git checkout vX.Y.Z
  2. Build a source package
    make srpm

Build for applicable releases

With a source RPM created, it's time to build updated packages for any existing stable repositories. This includes Fedora 41, Fedora 40 and, depending on the time of release, potentially Fedora 39. Traditionally, this step would be handled by running the koji build --tag dist-f41-updates path/to/src.rpm command. However, since autoqa is not yet packaged and available in Fedora repositories, updates are built locally using mock.

Update your mock configuration
You will need to update the mock configuration files in /etc/mock so that the autoqa package repositories are included. This means updating all mock configuration files of all systems you want to build RPMs for. For instance, if you are going to build for Fedora 16, you will add the following into /etc/mock/fedora-16-x86_64.cfg
[fedora-autoqa]
name=The autoqa project provides a basic framework for Fedora test automation
baseurl=http://repos.fedorapeople.org/repos/fedora-qa/autoqa/fedora-16/x86_64
enabled=1
skip_if_unavailable=1
gpgcheck=0
Information on autoqa package repositories is available at Install_and_configure_AutoQA.
  1. Build packages using mock for Fedora, specify version using DIST variable. For possible values for DIST, consult Packaging:DistTag
    make mock DIST=.fc41 
  2. Repeat the build procedure for all desired releases

Create updates

With packages built, it's time to submit them as updates. Traditionally, this step would be handled by using the bodhi update tool. However, since autoqa is not yet packaged and available in official Fedora repositories, a custom package repository is used to deliver updates.

  1. Mirror the autoqa package repository locally
    rsync -avz fedorapeople.org:/srv/repos/fedora-qa/autoqa ~/public_html/ ; cd autoqa/
  2. Add locally built packages to the desired repositories
    ./move-pkgs.sh path/to/autoqa.git/build/MOCK/*/*.rpm
    Simulating the updates-testing repository
    For pre-release or testing packages an alternative repository is available to mimic the official updates-testing Fedora repository. To submit packages into the fedora-autoqa-testing repository, add the command-line option -r testing. A complete example is included below.
    ./move-pkgs.sh -r testing path/to/autoqa.git/build/MOCK/*/*.rpm
  3. Update the yum repo metadata
    ./update-repos.sh
  4. Update remote repository with changes
     rsync -avz ~/public_html/autoqa fedorapeople.org:/srv/repos/fedora-qa/
  5. Change permissions on the server so that anyone in gitautoqa FAS group can update the repos
     chgrp -R gitautoqa /srv/repos/fedora-qa/autoqa
     chmod g+w -R /srv/repos/fedora-qa/autoqa

Cleanup tasks

Purging old release branches

If we are sure we will no longer work on older releases (e.g. before X.Y), we can also delete older release branches. If W < Y, then we can delete release-X.W:

  1. Make sure there's a tag at the tip of the branch and therefore no work is lost:
    git tag --contains origin/release-X.W
    This must output some tag (like vX.W.3). Otherwise the branch contains commits which are not part of any tag.
  2. Delete the remote branch:
    git push origin :release-X.W
  3. Prune the local branches (that no longer exist on the remote server):
    git remote prune origin

The same goes for deleting older major branches (branches release-Q.Y where Q < X).


Testing release

The following process concerns a testing release of AutoQA. We use this procedure when we want to deploy a testing version of AutoQA onto our staging server for thorough testing.

Build and install RPM

  1. SSH to the staging server and go to the AutoQA checkout directory (create one if you don't have one).
  2. Switch to the git branch you want to test, probably master:
    git pull; git checkout master
  3. Build an RPM from current HEAD using the same approach as in #Build for applicable releases, but with appending DEVEL=1 option:
    make mock DEVEL=1
    • Your user must be in the mock group to be able to run this.
  4. Install the RPM created in ./build/MOCK/<release>/.
    • Since we use git describe to generate package versions and sometimes we build and install package from other branches than master, you can actually end up with a package version that is lower than the one currently installed. Instead of using yum update autoqa-version.rpm use yum downgrade autoqa-version.rpm.
    • Be sure to inspect all .rpmnew and .rpmold files (if they are created, yum will tell you so) and merge the changes.