Jump to: navigation, search

Difference between revisions of "Rpm-packaging/ReviewGuidelines"

(Initial guideline for package specification template)
 
(→‎Version bumps)
 
(8 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
[https://github.com/openstack/rpm-packaging/tree/master/openstack/openstack-macros openstack-macros] - sub-project which allows to add or substitute required RPM macro used in SPEC template.<br />
 
[https://github.com/openstack/rpm-packaging/tree/master/openstack/openstack-macros openstack-macros] - sub-project which allows to add or substitute required RPM macro used in SPEC template.<br />
 
[https://github.com/openstack/pymod2pkg pymod2pkg] - project used for translation of python source name aka pypi name into Linux package name.<br />
 
[https://github.com/openstack/pymod2pkg pymod2pkg] - project used for translation of python source name aka pypi name into Linux package name.<br />
−
[https://github.com/openstack/renderspec renderspec] - main tool used for transformation from SPEC template into SPEC file.<br />
+
[https://github.com/openstack/renderspec renderspec] - main tool used for transformation from SPEC template into SPEC file. [http://docs.openstack.org/developer/renderspec/ documentaion]<br />
 +
 
 +
=Workflow for branches=
 +
* '''Current work'''
 +
All work must be done in the '''master''' branch of the particular project.
 +
* '''Back-ports/Cherry-picks'''
 +
In case of necessity changes proposed earlier to the '''master''' branch could be cherry-picked into ''stable'' branch.
 +
* '''Cases for back-port/cherry-picks:'''
 +
** Introduction of a new package if its metadata is valid as for master as for stable
 +
** There is no difference in amount of run-time and built-time dependencies
 +
** There is no difference in Version: between ''master'' and ''stable''
 +
** There are changes which are fixing %install or %files sections for a particular package
 +
In '''other cases''' updates should be proposed to a particular branch which requires an update!
  
−
=A little bit about syntax=
 
−
As was mentioned above, Jinja2 format was chosen and used for templates. <br />
 
−
''Example of syntax from template:''<br />
 
−
Requires:      &#123;&#123; 'pbr' &#124; py2pkg &#125;&#125; &gt;= 1.6
 
−
'''pbr''' - python project name.<br />
 
−
'''py2pkg''' - filter name used in the renderspec for transformation to system package name.<br /><br />
 
−
License:      &#123;&#123; 'Apache-2.0' &#124; license &#125;&#125;
 
−
'''Apache-2.0''' - common licence name.<br />
 
−
'''license'''  - filter name used in the renderspec for transformation in required format(as an example - [https://spdx.org/spdx-license-list SPDX] for [https://www.suse.com/ SUSE]).<br />
 
−
 
 
=Common rules=
 
=Common rules=
 
==Head==
 
==Head==
−
* '''Names''':
+
* '''Group''':
−
Project ''names'' used in template and processed by filter - are '''source project''' names.<br />
+
Setting up proper group for package is a requirement.<br>
−
''Example:''<br />
+
* '''Source0''':
−
Name:          &#123;&#123; 'oslo.utils' &#124; py2pkg &#125;&#125;
+
Source0 must points to existing tarball location, even if url constructed using macro.<br />
−
'''oslo.utils''' - means that native name of python projects is - ''oslo.utils''.<br />
 
−
* '''Sources''':
 
−
Source code source and project url should be specified!<br />
 
−
''Example:''<br />
 
−
%global sname pysomething<br />Version:    1.2.3<br />Url:        https:&#47;&#47;launchpad.net&#47;%{sname}<br />Source0:    https:&#47;&#47;pypi.python.org&#47;packages&#47;source&#47;p&#47;%{sname}/%{sname}-%{version}.tar.gz
 
−
* '''Versions''':
 
−
Lower bounds should be specified in both cases - for ''Requires'' and for ''BuildRequires'' entries at least for projects with versions set  in ''requirements.txt'' and ''test-requirements.txt'' files!<br />
 
 
''Example:''<br />
 
''Example:''<br />
−
  BuildRequires: &#123;&#123; 'netaddr' &#124; py2pkg &#125;&#125; >= 0.7.12
+
  Group:     Development/Libraries
−
  Requires: &#123;&#123; 'netaddr' &#124; py2pkg &#125;&#125; >= 0.7.12
+
  Source0:   https://pypi.python.org/packages/source/o/%{sname}/%{sname}-%{version}.tar.gz
  
 
==Documentation==
 
==Documentation==
Line 39: Line 34:
 
'''BuildRequires:''' - populated only with projects required for documentation build.<br />
 
'''BuildRequires:''' - populated only with projects required for documentation build.<br />
 
Please use ''%bcond_with docs'' in case of necessity!<br />
 
Please use ''%bcond_with docs'' in case of necessity!<br />
−
''Exmaple:''<br />
+
''Example:''<br />
 
  %if %{with docs}
 
  %if %{with docs}
 
  %package doc
 
  %package doc
Line 49: Line 44:
 
  ...
 
  ...
 
  %endif
 
  %endif
 +
 
==Tests==
 
==Tests==
 
Useful but not mandatory. All directives for unit tests must be set under '''%check''' section.<br />
 
Useful but not mandatory. All directives for unit tests must be set under '''%check''' section.<br />
 
All required for tests projects should be specified as '''BuildRequires:''' in the top of template.<br />
 
All required for tests projects should be specified as '''BuildRequires:''' in the top of template.<br />
 
Please use ''%bcond_with test'' in case of necessity!<br />
 
Please use ''%bcond_with test'' in case of necessity!<br />
−
''Exmaple:''<br />
+
''Example:''<br />
 
  %if %{with test}
 
  %if %{with test}
 
  BuildRequires: required for test projects
 
  BuildRequires: required for test projects
Line 63: Line 59:
 
  ...
 
  ...
 
  %endif
 
  %endif
 +
 +
==Version bumps==
 +
When updating the version of an existing package, please always add the following line in the commit message:
 +
 +
Depends-On: '''<change ID>'''
 +
 +
Where '''<change ID>''' is the change ID of the review for the openstack/requirements repository where the version for the package is updated. By doing this, we can ensure that no version will be updated before it is part of the upper-constraints.txt file.
 +
 +
See https://review.openstack.org/393121 for an example.
 +
 
==Misc but important!==
 
==Misc but important!==
 
Under %files section for each package in SPEC template:<br />
 
Under %files section for each package in SPEC template:<br />
 
* Section '''%doc''' should not include: ''HACKING*'', ''CONTRIBUTING*'' and ''AUTHORS''<br />
 
* Section '''%doc''' should not include: ''HACKING*'', ''CONTRIBUTING*'' and ''AUTHORS''<br />
 
* Section '''%license''' should be specified in case of ''LICENCE'' file availability in source code<br />
 
* Section '''%license''' should be specified in case of ''LICENCE'' file availability in source code<br />

Latest revision as of 14:08, 3 November 2016

Purpose

The main goal to use templates instead of SPEC - flexibility and unification. Templates made in Jinja2 format.
It means that templates made in one way after processing by renderspec tool will fit all supported Linux vendors(SUSE, Fedora, CentOS).

Tool-set

openstack-macros - sub-project which allows to add or substitute required RPM macro used in SPEC template.
pymod2pkg - project used for translation of python source name aka pypi name into Linux package name.
renderspec - main tool used for transformation from SPEC template into SPEC file. documentaion

Workflow for branches

  • Current work

All work must be done in the master branch of the particular project.

  • Back-ports/Cherry-picks

In case of necessity changes proposed earlier to the master branch could be cherry-picked into stable branch.

  • Cases for back-port/cherry-picks:
    • Introduction of a new package if its metadata is valid as for master as for stable
    • There is no difference in amount of run-time and built-time dependencies
    • There is no difference in Version: between master and stable
    • There are changes which are fixing %install or %files sections for a particular package

In other cases updates should be proposed to a particular branch which requires an update!

Common rules

Head

  • Group:

Setting up proper group for package is a requirement.

  • Source0:

Source0 must points to existing tarball location, even if url constructed using macro.
Example:

Group:      Development/Libraries
Source0:    https://pypi.python.org/packages/source/o/%{sname}/%{sname}-%{version}.tar.gz

Documentation

For *-doc package should be specified additional section which describes all meta-data for doc package.
BuildRequires: - populated only with projects required for documentation build.
Please use %bcond_with docs in case of necessity!
Example:

%if %{with docs}
%package doc
....
%endif

%if %{with docs}
%files doc
...
%endif

Tests

Useful but not mandatory. All directives for unit tests must be set under %check section.
All required for tests projects should be specified as BuildRequires: in the top of template.
Please use %bcond_with test in case of necessity!
Example:

%if %{with test}
BuildRequires: required for test projects
....
%endif

%if %{with test}
%check
...
%endif

Version bumps

When updating the version of an existing package, please always add the following line in the commit message: 

Depends-On: <change ID>

Where <change ID> is the change ID of the review for the openstack/requirements repository where the version for the package is updated. By doing this, we can ensure that no version will be updated before it is part of the upper-constraints.txt file.

See https://review.openstack.org/393121 for an example.

Misc but important!

Under %files section for each package in SPEC template:

  • Section %doc should not include: HACKING*, CONTRIBUTING* and AUTHORS
  • Section %license should be specified in case of LICENCE file availability in source code
Retrieved from "https://wiki.openstack.org/w/index.php?title=Rpm-packaging/ReviewGuidelines&oldid=137173"