Organization of maintenance for src:arduino
-------------------------------------------

This package is maintained with git-buildpackage(1).

It uses pristine-tar(1) to store enough information in git to generate bit
identical tarballs when building the package without having downloaded an
upstream tarball first.

When working with patches it is recommended to use "gbp pq import" to
import the patches, modify the source and then use "gbp pq export
--commit" to commit the modifications.

The changelog is generated using "gbp dch" so if you submit any changes
don't bother to add changelog entries but rather provide a nice git commit
message that can then end up in the changelog.

It is recommended to build the package with pbuilder using:

    gbp builpackage --git-pbuilder

For information on how to set up a pbuilder environment see the
git-pbuilder(1) manpage. In short:

    DIST=sid git-pbuilder create
    gbp clone https://salsa.debian.org/electronics-team/arduino/arduino.git
    cd arduino
    gbp buildpackage --git-pbuilder


Importing a new upstream version
--------------------------------

To minimize workload and decrease possible mistakes the preferred way to
import a new version is doing this by git-buildpackage and let d/gbp.conf
control the whole import process. Importing a new version is done by

  gbp import orig --sign-tags [--verbose] /path/to/arduino-$version.tar.xz

In case you need to modify the list of files or folders to exclude you can
tune this by modifying the section [import-orig] in d/gbp.conf. Don't forget
to also adjust d/copyright afterwards in case adjustments are needed.

Once the new version is imported you will need to check the patch queue is
applying or needs also adjustments. Also here git-buildpackage is helping
with this task.

  gbp pq import [--time-machine=x]

In case the upstream changes are small git will discover the changes and will
apply the patch from the queue. Depending on the upstream changes you will
need to use the option '--time-machine=' so git-buildpackage will apply the
patch queue to an older version from there you can use the rebase option.
In case '--time-machine=' was needed to get used you need to rebase the
patch-queue branch against the version in your packaging branch which is
mostly debian/sid (or debian/experimental).

  git rebase debian/sid

As usual you need to fix any rebasing issue if pop up. Once finished you
can export back the patch queue.

  gbp pq export

This will switch back to your working packaging branch and also creates all
files and folder under debian/patches/. Review the changes and commit your
work, please explain in the commit message what's new or what did change in
the patch queue. This will help later preparing the d/changelog entry!


Using of Debian packaged Java libraries, linking to packaged libraries
----------------------------------------------------------------------

As the Arduino IDE is an Java application it is requiring the availability of
the required libraries. Upstream is shipping them prebuilt and bundled within
the lib/ folder.
Debian can't use and pick them as there is no source available in the source
tarball from there the libraries could be rebuilt. Thus all these files are
getting cleaned out while import the source. But there is no need to rebuild
all the various libraries, all the used libs are available within the Debian
main archive. To get them usable all the required libraries need to get
linked back into the lib/ folder while the build process of the package.
This is done within the linking sequencer file 'arduino.links'.

To add such a linking you need to do some things to get the chain working.

1. Have a look at the .jar files within the lib/ folder of the upstream
   tarball.
2. Search the Debian package which is providing the used Java library.
3. Add an entry for the library to arduino.links it will get linked.
   Note! Don't use any versioned files, remove the version suffix from the
         upstream file name.
   Example: 'batik-1.8.jar' becomes 'batik.jar'
4. Check if the Depends field for the package arduino in debian/control needs
   an addition of the package that is providing the Java library you've
   added. Keep new added packages in d/control please in alphabetical order!

There are small exceptions between used upstream Java libraries and by Debian
provided and used libraries! For the follow libraries upstream is using
different or other versions.

 Upstream version     | Debian version
 ---------------------+---------------
 bcpg-jdk15on-*.jar   | bcpg-*.jar
 bcprov-jdk15on-*.jar | bcprov-*.jar
 jssc-*-arduino4.jar  | jssc.jar

The first two libraries working fine with the IDE, from the modified jssc
library is no source available so it can't get rebuilt nor do we know what
Arduino LCC has modified.
