Blog

Krok za krokem ke zveřejnění OpenSource

• Jazyk/platforma: Java
• Buildovací nástroj: Maven
• Verzovací nástroj:Mercurial
• Hosting: SourceForge
• Hosting stránek: SourceForge
• Hosting mavenu: SonaType
• Licence projektu: LGPL

Celá idea je v tom, že pokud vyrobím nějakou java knihovnu a chci ji zveřejnit tak, aby uživatelé s mavenem nebo některým z dalších nástrojů, které se umí spojit s tímto repozitářem, mohli použít moji knihovnu na základě přidání groupId a artifactId do POMu nebo jiného buildovacího nástroje, musím projít pár dalšími kroky k tomu, abych svůj kód dostal do centrálního repozitáře mavenu.

Celkový proces díky některým prodlevám a schvalovacím procesům bude trvat přibližně 5 až 8 pracovních dní.

Veškeré uvedené příklady jsou na konkrétním produktu. Některé kroky, které v tomto návodu nalezenete, mohou být na první pohled divné, avšak při jejich nedodržení můžete později narazit zejména na podmínky užívání některých serverů, např. Sonatype.

Než začnete, zrekapitulujte si základní důležitá fakta o svém projektu:

• Máte vztah k doméně - optimálně ji vlastníte - podle jejího názvu pak nastavujete groupId, tedy v případě groupId=cz.wicketstuff.boss, jsem vlastníkem domény wicketstuff.cz
• Projekt je pod některou ze svobodných licencí, v našem případě je to LGPL verze 3
• Třídy zdrojového kódu jsou pojmenovány v souladu s doménou, tedy v našem případě začínají doménou a projektem, tedy cz.wicketstuff.boss.flow
• Zkontrolujte, že máte přístupy k DNS záznamům pro Vaši doménu

Důležitý software

Před započetím celého procesu si nainstalujte potřebný software a seznamte se s případnými odlišnostmi v používání mezi systémem Linux a Windows:

• openssl (libovolnou knihnovnu, která umí generovat klíče)
• ssh klient (pro uživatel windows putty)
• gpg(software pro digitální podpis)
• maven
• mercurial nebo git

Všechny ukázky v tomto článku využívají syntax pro Linux, pokud užíváte Windows, zjistěte si zejména nastavení cesty (path) pro spustitelné programy, event. rozdílnosti v užívání programů, např. ssh vs. putty. V příkladech je zde uváděn mercurial, alternativa s Git je prakticky identická s minimem změn.

Založení projektu na SourceForge

• Vytvořte si, pokud ještě nemáte, dvojici soukromého a veřejného klíče ssh-keygen -t  rsa (můžete použít i klíč silnější šifry typu DSA) a založte si účet na https://sourceforge.net/user/registration, v mém případě účet martinstrejc
• Nahrajte svůj veřejný klíč (soubor id_rsa.pub z adresáře .ssh) do svého profilu, který naleznete v nastavení účtu; Home -> Account -> Services.
  Pozor: Aktivace klíče na SF trvá několik dní
• Založte projekt na SF (v našem případě BOSS Flow, mountpoint: boss-flow)
• V administraci projektu (BOSS Flow -> Admin -> Tools) přidejte
  Summary, mountpoint: summary,
  Mercurial, mountpoint: code,
  Source Code, mountpoint: source,
  Files, mountpoint: files,
  Vhost: mountpoint: sfx-vhost
  Tickets: mountpoint: tickets
• Přejděte do administrace vhost a přidejte doménu, v našem případě boss-flow.wicketstuff.cz
• Na své doméně nastavte směrování pro veřejné stránky, v našem případě záznam CNAME: boss-flow.wicketstuff.cz -> vhost.sourceforge.net
  

  Pozor: Propagace DNS záznamů tvá přibližně den, do té doby na tuto adresu nepřistupujte, pak ji ozkoušejte zadáním adresy do prohlížeče, (v našem případě tedy http://boss-flow.wicketstuff.cz), měla by se objevit výchozí generická stránka projektu.

• Vyzkoušejte přihlášení do shellu sourceforge, při přihlášení je potřeba použít jméno uživatele a název projektu, tedy ssh -t martinstrejc,boss-flow@shell.sourceforge.net create

  Pozor: Tento shell je pouze dočasný, jeho platnost je 180 minut, pak sám zanikne. Je možné jej také předčasně ukončit z konzole. Pokud již tento shell vytvoříte a je aktivní, přihlašujete se standardně ssh -t martinstrejc,boss-flow@shell.sourceforge.net

  Více o SF shellu na stránkách https://sourceforge.net/apps/trac/sourceforge/wiki/Shell%20service

Příprava Mavenu

Před deployem je potřeba zkontrolovat a řádně připravit projekt mavenu, tedy soubor POM.xml

Následující ukázka je plně funkční, byť některé věci by asi šly řešit trochu lépe.

• Zkontrolujte si název projektu, popis, verzi připravte jako SNAPSHOT, doporučuji užívat 2- nebo 3-číselné označování verzí.

  Fragment POM.xml

  <groupId>cz.wicketstuff.boss</groupId>
<artifactId>boss-flow</artifactId>
<version>1.2.1-SNAPSHOT</version>
<name>BOSS Flow Framework</name>
<description>Workflow control and configuration java framework</description>
• Přidejte informace o stránkách projektu

  Fragment POM.xml

  <url>http://boss-flow.wicketstuff.cz</url>
• Přidejte informace o licenci a vydavateli knihovny

  Fragment POM.xml

  <inceptionYear>2012</inceptionYear>
<organization>
<name>BOSS Team @ Et netera, a.s.</name>
<url>http://boss.wicketstuff.cz</url>
</organization>
<licenses>
<license>
<name>GNU LGPLv3</name>
<url>http://www.gnu.org/licenses/lgpl-3.0.html</url>
<distribution>repo</distribution>
</license>
</licenses>
• Přidejte informace o verzovacím systému (zde je to včetně přítupů, což není úplně korektní řešení, ale je bez problémů funkční)
  <scm>
<connection>scm:hg:ssh://martinstrejc@hg.code.sf.net/p/boss-flow/source</connection>
<developerConnection>scm:hg:ssh://martinstrejc@hg.code.sf.net/p/boss-flow/source</developerConnection>
<url>https://hg.code.sf.net/p/boss-flow/source</url>
</scm>
• Přidejte informace o vývojářích a mailinglistech (maillist si zařiďte na své doméně nebo na sourceforge)

  Fragment POM.xml

  <mailingLists>
<mailingList>
<name>BOSS Team @ Et netera</name>
<post>boss@etnetera.cz</post>
</mailingList>
</mailingLists>
<developers>
<developer>
<name>Martin Strejc</name>
<email>martin.strejc@etnetera.cz</email>
<roles>
<role>architect</role>
<role>developer</role>
<role>tester</role>
</roles>
</developer>
</developers>
• Přidejte pluginy pro generování dokumentace a její deploy přes SSH

  Fragment POM.xml

  <plugins>
<plugin>
<inherited>true</inherited>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.5</version>
<configuration>
<source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.2.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.2</version>
<dependencies>
<dependency>
<groupId>org.apache.maven.wagon</groupId>
<artifactId>wagon-ssh</artifactId>
<version>1.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</pluginManagement>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<links>
<link>http://docs.oracle.com/javase/7/docs/api/</link>
</links>
<show>private</show>
</configuration>
</plugin>
</plugins>
</reporting>

• Přidejte profil pro release a podepisování knihoven

  Fragment POM.xml

  <profiles>
<profile>
<id>release-sign-artifacts</id>
<activation>
<property>
<name>performRelease</name>
<value>true</value>
</property>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.1</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>

Deploy a release pomocí OSS Sonatype

Do centrálního repozitáře se dostaneme prostřednictvím software Nexus provozovaného společností Sonatype jako veřejný repozitář s podporou pro OpenSource projekty. Sonatype má poměrně přesně definovaná pravidla jak pro obsah souboru POM, tak pro organizační záležitosti k releasu knihoven do dalších repozitářů.

• Vygenerute si soubor s podpisem a zaregistrujte tento podpis
  viz https://docs.sonatype.org/display/Repository/How+To+Generate+PGP+Signatures+With+Maven
  

  Pozor: Zapamatujte si passphrase, nelze již změnit ani zjistit! Během generování klíče je obvykle generátorem náhodných čísel vyžadován pohyb myší nebo psaní na klávesnici.

  
  

  Sekvence příkazů

  gpg --gen-key
gpg --list-keys
   vrátí něco jako
  pub 1024D/C6EED57A 2010-01-13 gpg --list-secret-keys
gpg --keyserver hkp://pool.sks-keyservers.net --send-keys C6EED57A
   použijte prve získané číslo klíče
• Zaregistrujte se u Sonatype https://oss.sonatype.org/
  kuchařka je tady https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide

  3)
  Založte v JIRA https://issues.sonatype.org/browse/OSSRHissue typu New Project, do názvu uveďte groupId.
  

  Informace o issue

  Issue type: New Project
Group Id: cz.wicketstuff
Project URL: http://boss-flow.wicketstuff.cz
SCM url: https://hg.code.sf.net/p/boss-flow/source
Username: martin.strejc

  Pozor: groupId jsou první dva fragmenty groupId z POMu. Získáváte tedy přístup k synchronizaci čehokoliv na dalších úrovní. Vyřízení tohoto úkolu trvá přibližně 1 až 2 dny.

• Při úspěšném vyřízení byste měli dostat následující zprávu od řešitele úkolu
  
  Configuration has been prepared, now you can:
  
  Deploy snapshot artifacts into repository https://oss.sonatype.org/content/repositories/snapshots Deploy
  release artifacts into the staging repository https://oss.sonatype.org/service/local/staging/deploy/maven2
  Promote staged artifacts into repository 'Releases' Download snapshot and release artifacts from group https://oss.sonatype.org/content/groups/public
  Download snapshot, release and staged artifacts from staging group https://oss.sonatype.org/content/groups/staging
  
  please comment on this ticket when you promoted your first release, thanks
• Proveďte deploy SNAPSHOTU

  Pozor: Před deployem si vytvořte terminál. Příkaz mvn spouštějte z adresáře svého projektu.

  Sekvence příkazů

  ssh -t martinstrejc,boss-flow@shell.sf.net create
mvn site:site mvn site:deploy
mvn deploy
• Proveďte release
  zde je kuchařka http://www.sonatype.com/books/nexus-book/reference/staging-sect-managing-staging.html

  Pozor: Před releasem si vytvořte terminál. Po releasu uzavřete repozitář. Pokud děláte tuto akci poprvé, přidejte ještě komentář do JIRA, že jste již svůj artefakt nahráli. Budete potřebovat passphrasse k vygenerovaného podpisu. Pro vyřízení synchronizace opět předpokládejte přibližně 1 až 2 dny.

  Sekvence příkazů

  mvn release:clean
mvn release:prepare mvn release:perform -Darguments=-Dgpg.passphrase=MOJE_GPG_PASSPHRASEE
• Uzavřete staging repository v Sonatype
  zde je kuchařka http://www.sonatype.com/books/nexus-book/reference/staging-sect-managing-staging.html
  pro svůj repozitář zvolte Close a pak Release

  Pozor: Dokud nedojde k uzavření repozitáře, nikam se jeho obsah nezpropaguje. Před uzavřením vidíte i obsah tohoto repozitáře, raději si jej překontrolujte.

• Jste tam!!!
  Měli byste svůj artefakt najít podle jména v centrálním repozitáři,
  http://search.maven.org/
  tedy v našem případě http://search.maven.org/#browse|-1932462777

HODNĚ ŠTĚSTÍ

a napiště nám mail, zda se vám někomu povedlo to dotáhnout, díky a ještě jednou hodně zdaru :-)