Blog

 

 Tagcloud

 Kalendář akcí

 Twitter

 
22. ledna
2013

Krok za krokem ke zveřejnění OpenSource

Autor: Martin Strejc | upraveno: 25. 1. 2013 | štítky: OpenSource, Maven, Sonatype, Nexus, Deploy

Rád bych pomohl těm, kteří by chtěli svůj opensource zveřejnit ze svého PC až do maven repozitářů. Článek vychází z poslední zkušenosti a ukazuje kompletní postup.

Vzhledem k faktu, že za OpenSource lze považovat témeř jakýkoliv program či knihovnu a zveřejněnit jej můžete kamkoliv, uvedu nejprve specifikaci produktu.

  • 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 :-)