Sometimes you will need to change the upstream source for various reasons. We'll try to document all know cases and their solutions.

Missing tests

We prefer to run all provided tests and sometimes upstream does not add tests in the gems but they will be available from their upstream source repo (usually github).

  1. Run gem2deb to create initial dsc. Use git-import-dsc --pristine-tar to import it.

  2. Use github tags to download the latest version. Update debian/watch to point to (see debian/watch#GitHub) and run uscan --verbose --download-current-version. OR You can copy the link to zip file and use wget to download the tarball (just change .zip to .tar.gz) It is a good idea to add gh to the version in case the same version is already in the archive, so we know we downloaded from github.

  3. Remove the upstream tag by git tag -d upstream/xxx. Use git-import-orig to import the github tarball and mention upstream version as 3.0.7gh.

  4. Update changelog entry. For example, 3.0.7gh-1, if upstream version is 3.0.7

  5. Update watch file so it uses github tags if you chose to download tar.gz directly earlier. ruby-subexec has an example

  6. Open a github issue with upstream to include tests in gem. Usually upstreams respond favorably.

  7. Create debian/README.source and mention why we are using github tarball instead of gem file.

Missing tests and missing tags

  1. Download master branch as a tarball and use +git.yyyymmdd.1234567 suffix, where yyyymmdd correspond to the date of the last commit in master, and 1234567 are the first digits of the commit's SHA.
    1. Run gem2deb to create initial dsc. Use git-import-dsc --pristine-tar to import it
    2. Import the upstream tarball with git import orig and provide upstream version like 3.0.7+git.20130622.ab34f107, if the latest known upstream version is 3.0.7, and the last commit in the master branch is on 2013/06/22.
    3. Update changelog entry as above.
    4. Create debian/README.source and mention why we are using github master tarball instead of gem file.
    5. Request upstream to tag releases and include tests in releases.
    6. add a dversionmangle and a comment to look at README.source in debian/watch

# Using github master tarball, see README.source
opts=dversionmangle=s/\+git\.[0-9]*\.[a-zA-Z0-9]*// \ .*/messagebus_ruby_api-(.*).tar.gz

If it has embedded libraries in vendor directory / non distribuable files

For embedded libraries removed, the suffix is +ds or +debian. For non distribuable files removed, the suffix is +dfsg.

3. Easier Method

Step a. Create debian/gbp.conf with specifying the files/directories you need to filter out. Example is

filter = ['ext/version_sorter/frameworks', 'ext/version_sorter/version_sorter.xcodeproj']
filter-pristine-tar = True

Remember not to put the trailing '/' at the end of directory names.

Step b. run

git-import-orig --pristine-tar

Step c. When it ask for version, add version number+dfsh eg: 0.5.0+dfsg

Step d. Check git pristine branch and git tag for existence of +dfsg stuff

Step e. Update changelog file to mention version as +dfsg eg :

ruby-version-sorter (1.1.0+dfsg-1) unstable; urgency=medium

Step f. Update watch file - Insert

opts=dversionmangle=s/\+(debian|dfsg|ds|deb)(\.\d+)?$// \

after the first line (i.e the line with version= )

Step g. Build package