User:Spot/GitHub Guidelines

From FedoraProject

< User:Spot(Difference between revisions)
Jump to: navigation, search
(Created page with "=== Github === As many upstreams use github for their source control, it is worth covering how to handle that source in a Fedora Package. Github provides a mechanism to crea...")
 
Line 14: Line 14:
 
Once the commit hash is known, you can define it in your spec file as follows:
 
Once the commit hash is known, you can define it in your spec file as follows:
  
<code>
+
<pre>
 
%global commit c5a4525bfa3bd9997834d0603c40093e50e3fd19
 
%global commit c5a4525bfa3bd9997834d0603c40093e50e3fd19
 
%global shortcommit %(c=%{commit}; echo ${c:0:7})
 
%global shortcommit %(c=%{commit}; echo ${c:0:7})
</code>
+
</pre>
  
 
For the source tarball, you should use this syntax:
 
For the source tarball, you should use this syntax:
<code>
+
<pre>
 
Source0:        https://github.com/$OWNER/$PROJECT/archive/%{commit}/%{name}-%{version}-%{shortcommit}.tar.gz
 
Source0:        https://github.com/$OWNER/$PROJECT/archive/%{commit}/%{name}-%{version}-%{shortcommit}.tar.gz
  
Line 27: Line 27:
 
%prep
 
%prep
 
%setup -qn %{name}-%{commit}
 
%setup -qn %{name}-%{commit}
</code>
+
</pre>
  
 
In this syntax, $OWNER must be replaced with the github username for the project's owner, and
 
In this syntax, $OWNER must be replaced with the github username for the project's owner, and

Revision as of 17:30, 19 December 2012

Github

As many upstreams use github for their source control, it is worth covering how to handle that source in a Fedora Package.

Github provides a mechanism to create tarballs on demand, either from a specific commit revision, or from a specific tag. If the upstream does not create tarballs for releases, you can use this mechanism to produce them. If the upstream does create tarballs you should use them as tarballs provide an easier trail for people auditing the packages.

For a number of reasons (immutability, availability, uniqueness), you must use the full commit revision hash when referring to the sources.

The full 40-character hash can be copied from the github web interface at ​https://github.com/OWNER/PROJECT/tags or by cloning the repository and using git rev-parse TAG

In this example, TAG is the tag for the source revision we are interested in.

Once the commit hash is known, you can define it in your spec file as follows:

%global commit c5a4525bfa3bd9997834d0603c40093e50e3fd19
%global shortcommit %(c=%{commit}; echo ${c:0:7})

For the source tarball, you should use this syntax:

Source0:        https://github.com/$OWNER/$PROJECT/archive/%{commit}/%{name}-%{version}-%{shortcommit}.tar.gz

...

%prep
%setup -qn %{name}-%{commit}

In this syntax, $OWNER must be replaced with the github username for the project's owner, and $PROJECT must be replaced with the github identifier for the project.

If the release corresponds to a github Tag with a sane numeric version, you must use that version to populate the Version field in the spec file. If it does not, look at the source code to see if a version is indicated there, and use that value. If no numeric version is indicated in the code, you may set Version to 0, and treat the package as a "pre-release" package (and make use of the %{shortcommit} macro). See Packaging:NamingGuidelines#Pre-Release_packages for details.

Alternately, if you are using a specific revision from github that is either a pre-release revision or a post-release revision, you must follow the "snapshot" guidelines. They are documented here: Packaging:NamingGuidelines#Snapshot_packages. You can substitute %{shortcommit} for %{checkout} in that section.

Keep in mind that github tarballs are generated on-demand, so their modification dates will vary and cause checksum tests to fail. Reviewers will need to use diff -r to verify the tarballs.