2013
Krok za krokem ke zveřejnění OpenSource
Autor: Martin Strejc | upraveno: 25. 1. 2013 | štítky: OpenSource, Maven, Sonatype, Nexus, DeployRá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.
- 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
vrátí něco jako
gpg --list-keys
pub 1024D/C6EED57A 2010-01-13 gpg --list-secret-keys
použijte prve získané číslo klíče
gpg --keyserver hkp://pool.sks-keyservers.net --send-keys C6EED57A
- Zaregistrujte se u Sonatype https://oss.sonatype.org/
kuchařka je tady https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide3)
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.strejcPozor: 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.htmlPozor: 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 ReleasePozor: 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 :-)