DEVNOTES.txt - ignite - Git at Google

 A Note about Invoking Maven
 ===========================

 Apache Ignite build system uses Maven Wrapper to simplify and standardize build process. On different operating
 systems, it should be run slightly differently:

 * On Unix-like systems (including Cygwin, WSL, git-bash), it's `./mvnw <arguments>`
 * On Windows (in PowerShell), it's `./mvnw <arguments>` as well
 * On Windows (in cmd shell), it's `.\mvnw <arguments>` or `mvnw <arguments>` (in older versions)

 Further in our documentation, we always use the ./mvnw form. Please adapt it to your system if needed.

 Apache Ignite Maven Build Instructions
 ======================================
 1) Compile and install:

         ./mvnw clean install -Pall-java,all-scala,licenses -DskipTests

    or if you have to build .NET part as well, use the following command:
    (Note that 'doxygen', `docfx`, '.NET Core SDK 3.1', 'PowerShell' should be installed before running this command.)

         ./mvnw clean install -Pall-java,all-scala,licenses,platforms -DskipTests -DclientDocs

 2) Javadoc generation (optional):

         ./mvnw initialize -Pjavadoc

 3) Build Apache Ignite assembly:

         ./mvnw initialize -Prelease

    Look for apache-ignite-<version>-bin.zip in ./target/bin directory.

 4) Build Apache Ignite slim edition assembly:

         ./mvnw initialize -Prelease -Dignite.edition=apache-ignite-slim

    Look for apache-ignite-slim-<version>-bin.zip in ./target/bin directory.


 Apache Ignite with LGPL Maven Build Instructions
 ================================================
 1) Compile and install:

         ./mvnw clean install -Pall-java,all-scala,licenses -DskipTests

    or if you have to build .NET part as well, use the following command:
    (Note that 'doxygen', `docfx`, '.NET Core SDK 3.1', 'PowerShell' should be installed before running this command.)

         ./mvnw clean install -Pall-java,all-scala,licenses,platforms -DskipTests -DclientDocs

 2) Javadoc generation with LGPL (optional):

         ./mvnw initialize -Pjavadoc,lgpl

 3) Build Apache Ignite assembly with LGPL dependencies:

         ./mvnw initialize -Prelease,lgpl -Dignite.edition=apache-ignite-lgpl

    Look for apache-ignite-lgpl-<version>-bin.zip in ./target/bin directory.


 Apache Ignite with NUMA allocator Build Instructions (Linux only)
 ================================================
 1) Install dependencies as described at modules/numa-allocator/README.md.

 2) Compile and install:

         ./mvnw clean install -Pall-java,licenses -DskipTests

    or if you have built Apache Ignite.NET on the first step use following command:
    (Note that 'doxygen' should be installed before running this command.)

         ./mvnw clean install -Pall-java,licenses -DskipTests -DclientDocs

 3) Javadoc generation with NUMA allocator (optional):

         ./mvnw initialize -Pjavadoc,numa-allocator

 4) Build Apache Ignite assembly with NUMA allocator:

         ./mvnw initialize -Prelease,numa-allocator

    Look for apache-ignite-<version>-bin.zip in ./target/bin directory.


 Ignite C++ Build Instructions
 =============================
 Instructions can be found at modules/platforms/cpp/DEVNOTES.txt.


 Apache Ignite RPM Package Build Instructions
 ============================================
 1) Build Apache Ignite binary archive (instructions above)

 2) Run packaging script and follow messages if they required interaction

         packaging/package.sh --rpm

    Packages will be available in packaging/ directory


 Apache Ignite DEB Package Build Instructions
 ============================================
 1) Build Apache Ignite binary archive (instructions above)

 2) Build Apache Ignite RPM package (also above)

 3) Run packaging script and follow messages if they required interaction

         packaging/package.sh --deb

    Packages will be available in packaging/ directory

    NOTE: to build both packages type at once, run

         packaging/package.sh --rpm --deb


 Install and Run Apache Ignite from packages
 ===========================================
 1) Install package with YUM or APT respectively

         yum localinstall -y apache-ignite-<version>.noarch.rpm
             or
         dpkg -i apache-ignite_<version>_all.deb

 2) Start Apache Ignite service

         systemctl start apache-ignite@<config name>

    NOTE: <config name> - relative to /etc/apache-ignite configuration file name

    Example:

         systemctl start apache-ignite@default-config.xml

 3) See logs in /var/log/apache-ignite or journalctl -xe


 Ignite Release Instructions
 ===========================
 1) Use your people.apache.org/keys/committer/<username>.asc key to generate KEYS file.
    Download https://dist.apache.org/repos/dist/release/ignite/KEYS and append you key using commands:

         gpg --list-sigs <keyname> >> KEYS
         gpg --armor --export <keyname> >> KEYS

    Upload modified KEYS file.

 2) Specify gpg profile at settings.xml. It will be used to sign sources and artifacts.

 <profile>
    <id>gpg</id>
    <properties>
       <gpg.keyname>keyname</gpg.keyname>
       <gpg.passphrase>passphrase</gpg.passphrase>
    </properties>
 </profile>

    Ensure you have RELEASE (not SNAPSHOT) version at Ignite poms.
    Maven release plugin release:prepare goal can be used to make release tag.

 3) Deploy Ignite release candidate to maven repository and dev-svn, make tag:

    3.1) Deploy Ignite to maven repository, prepares sources and binaries.

                 ./mvnw deploy -Papache-release,gpg,all-java,all-scala,licenses,deploy-ignite-site -Dignite.edition=apache-ignite -DskipTests

    3.2) Javadoc generation:

                 ./mvnw initialize -Pjavadoc

    3.3) Assembly Apache Ignite:

                 ./mvnw initialize -Prelease

    NOTE: Nexus staging (repository.apache.org) should be closed with appropriate comment contains release version and
    release candidate number, for example "Apache Ignite 1.0.0-rc7", when `./mvnw deploy` finished.

    3.5) Checkout https://dist.apache.org/repos/dist/dev/ignite svn. Create release candidate folder with name
         equals to release version with "-rc*" ending, for example "1.0.0-rc7", at svn root.
         Copy /target/site folder content to svn/ignite/<rc-version> folder and commit with appropriate comment.

    3.6) Make appropriate git tag for release candidate, for example "ignite-X.Y.Z-rc1".

 4) Start vote based on https://dist.apache.org/repos/dist/dev/ignite/<rc-version>.

 5) Release nexus staging, move binaries and sources from https://dist.apache.org/repos/dist/dev/ignite/<rc-version>
    to https://dist.apache.org/repos/dist/release/ignite/<version> when version accepted.
    Use svn mv ^/dev/ignite/<rc-version> ^/release/ignite/<version> command for proper moving.

 6) Make appropriate git tag for released version, for example "ignite-X.Y.Z".

 7) Send an email to dev@ignite.apache.org contains release svn url.


 JCache TCK compliance
 ======================
 To test compliance with JCache TCK use:

         ./mvnw test -P-release,jcache-tck -pl :ignite-core -am

 Run tests
 =========
 To run tests locally use:

         ./mvnw clean test -U -Plgpl,examples,-clean-libs,-release -Dmaven.test.failure.ignore=true -DfailIfNoTests=false -Dtest=%TEST_PATTERN%

 For example, %TEST_PATTERN% can be 'org.apache.ignite.testsuites.IgniteBasicTestSuite' or 'GridCacheLocalAtomicFullApiSelfTest#testGet'

 Test suites
 =========
 All unit tests must be included in any test suite. Travis runs a check for that. To check it locally run for the root project:

         ./mvnw test -Pcheck-test-suites

 If you want to check a single module only:

 1) Add ignite-tools dependency to the test scope of the module.

 2) Install ignite-tools with command:

     ./mvnw install -Pcheck-test-suites

 3) Run tests in the module:

     ./mvnw test

 Apache RAT Instructions
 =======================
 To check license headers use:

         ./mvnw clean validate -Pcheck-licenses

 For more information (e.g. exclude list) see "check-licenses" profile in "parent/pom.xml".


 Useful Release Commands
 =======================
 ZIP:
         zip -r9 apache-ignite-X.X.X-src.zip apache-ignite-X.X.X-src
 GPG:
         gpg --armor --output apache-ignite-X.X.X-src.zip.asc --detach-sig apache-ignite-X.X.X-src.zip
	A Note about Invoking Maven
	===========================

	Apache Ignite build system uses Maven Wrapper to simplify and standardize build process. On different operating
	systems, it should be run slightly differently:

	* On Unix-like systems (including Cygwin, WSL, git-bash), it's `./mvnw <arguments>`
	* On Windows (in PowerShell), it's `./mvnw <arguments>` as well
	* On Windows (in cmd shell), it's `.\mvnw <arguments>` or `mvnw <arguments>` (in older versions)

	Further in our documentation, we always use the ./mvnw form. Please adapt it to your system if needed.

	Apache Ignite Maven Build Instructions
	======================================
	1) Compile and install:

	./mvnw clean install -Pall-java,all-scala,licenses -DskipTests

	or if you have to build .NET part as well, use the following command:
	(Note that 'doxygen', `docfx`, '.NET Core SDK 3.1', 'PowerShell' should be installed before running this command.)

	./mvnw clean install -Pall-java,all-scala,licenses,platforms -DskipTests -DclientDocs

	2) Javadoc generation (optional):

	./mvnw initialize -Pjavadoc

	3) Build Apache Ignite assembly:

	./mvnw initialize -Prelease

	Look for apache-ignite-<version>-bin.zip in ./target/bin directory.

	4) Build Apache Ignite slim edition assembly:

	./mvnw initialize -Prelease -Dignite.edition=apache-ignite-slim

	Look for apache-ignite-slim-<version>-bin.zip in ./target/bin directory.


	Apache Ignite with LGPL Maven Build Instructions
	================================================
	1) Compile and install:

	./mvnw clean install -Pall-java,all-scala,licenses -DskipTests

	or if you have to build .NET part as well, use the following command:
	(Note that 'doxygen', `docfx`, '.NET Core SDK 3.1', 'PowerShell' should be installed before running this command.)

	./mvnw clean install -Pall-java,all-scala,licenses,platforms -DskipTests -DclientDocs

	2) Javadoc generation with LGPL (optional):

	./mvnw initialize -Pjavadoc,lgpl

	3) Build Apache Ignite assembly with LGPL dependencies:

	./mvnw initialize -Prelease,lgpl -Dignite.edition=apache-ignite-lgpl

	Look for apache-ignite-lgpl-<version>-bin.zip in ./target/bin directory.


	Apache Ignite with NUMA allocator Build Instructions (Linux only)
	================================================
	1) Install dependencies as described at modules/numa-allocator/README.md.

	2) Compile and install:

	./mvnw clean install -Pall-java,licenses -DskipTests

	or if you have built Apache Ignite.NET on the first step use following command:
	(Note that 'doxygen' should be installed before running this command.)

	./mvnw clean install -Pall-java,licenses -DskipTests -DclientDocs

	3) Javadoc generation with NUMA allocator (optional):

	./mvnw initialize -Pjavadoc,numa-allocator

	4) Build Apache Ignite assembly with NUMA allocator:

	./mvnw initialize -Prelease,numa-allocator

	Look for apache-ignite-<version>-bin.zip in ./target/bin directory.


	Ignite C++ Build Instructions
	=============================
	Instructions can be found at modules/platforms/cpp/DEVNOTES.txt.


	Apache Ignite RPM Package Build Instructions
	============================================
	1) Build Apache Ignite binary archive (instructions above)

	2) Run packaging script and follow messages if they required interaction

	packaging/package.sh --rpm

	Packages will be available in packaging/ directory


	Apache Ignite DEB Package Build Instructions
	============================================
	1) Build Apache Ignite binary archive (instructions above)

	2) Build Apache Ignite RPM package (also above)

	3) Run packaging script and follow messages if they required interaction

	packaging/package.sh --deb

	Packages will be available in packaging/ directory

	NOTE: to build both packages type at once, run

	packaging/package.sh --rpm --deb


	Install and Run Apache Ignite from packages
	===========================================
	1) Install package with YUM or APT respectively

	yum localinstall -y apache-ignite-<version>.noarch.rpm
	or
	dpkg -i apache-ignite_<version>_all.deb

	2) Start Apache Ignite service

	systemctl start apache-ignite@<config name>

	NOTE: <config name> - relative to /etc/apache-ignite configuration file name

	Example:

	systemctl start apache-ignite@default-config.xml

	3) See logs in /var/log/apache-ignite or journalctl -xe


	Ignite Release Instructions
	===========================
	1) Use your people.apache.org/keys/committer/<username>.asc key to generate KEYS file.
	Download https://dist.apache.org/repos/dist/release/ignite/KEYS and append you key using commands:

	gpg --list-sigs <keyname> >> KEYS
	gpg --armor --export <keyname> >> KEYS

	Upload modified KEYS file.

	2) Specify gpg profile at settings.xml. It will be used to sign sources and artifacts.

	<profile>
	<id>gpg</id>
	<properties>
	<gpg.keyname>keyname</gpg.keyname>
	<gpg.passphrase>passphrase</gpg.passphrase>
	</properties>
	</profile>

	Ensure you have RELEASE (not SNAPSHOT) version at Ignite poms.
	Maven release plugin release:prepare goal can be used to make release tag.

	3) Deploy Ignite release candidate to maven repository and dev-svn, make tag:

	3.1) Deploy Ignite to maven repository, prepares sources and binaries.

	./mvnw deploy -Papache-release,gpg,all-java,all-scala,licenses,deploy-ignite-site -Dignite.edition=apache-ignite -DskipTests

	3.2) Javadoc generation:

	./mvnw initialize -Pjavadoc

	3.3) Assembly Apache Ignite:

	./mvnw initialize -Prelease

	NOTE: Nexus staging (repository.apache.org) should be closed with appropriate comment contains release version and
	release candidate number, for example "Apache Ignite 1.0.0-rc7", when `./mvnw deploy` finished.

	3.5) Checkout https://dist.apache.org/repos/dist/dev/ignite svn. Create release candidate folder with name
	equals to release version with "-rc*" ending, for example "1.0.0-rc7", at svn root.
	Copy /target/site folder content to svn/ignite/<rc-version> folder and commit with appropriate comment.

	3.6) Make appropriate git tag for release candidate, for example "ignite-X.Y.Z-rc1".

	4) Start vote based on https://dist.apache.org/repos/dist/dev/ignite/<rc-version>.

	5) Release nexus staging, move binaries and sources from https://dist.apache.org/repos/dist/dev/ignite/<rc-version>
	to https://dist.apache.org/repos/dist/release/ignite/<version> when version accepted.
	Use svn mv ^/dev/ignite/<rc-version> ^/release/ignite/<version> command for proper moving.

	6) Make appropriate git tag for released version, for example "ignite-X.Y.Z".

	7) Send an email to dev@ignite.apache.org contains release svn url.


	JCache TCK compliance
	======================
	To test compliance with JCache TCK use:

	./mvnw test -P-release,jcache-tck -pl :ignite-core -am

	Run tests
	=========
	To run tests locally use:

	./mvnw clean test -U -Plgpl,examples,-clean-libs,-release -Dmaven.test.failure.ignore=true -DfailIfNoTests=false -Dtest=%TEST_PATTERN%

	For example, %TEST_PATTERN% can be 'org.apache.ignite.testsuites.IgniteBasicTestSuite' or 'GridCacheLocalAtomicFullApiSelfTest#testGet'

	Test suites
	=========
	All unit tests must be included in any test suite. Travis runs a check for that. To check it locally run for the root project:

	./mvnw test -Pcheck-test-suites

	If you want to check a single module only:

	1) Add ignite-tools dependency to the test scope of the module.

	2) Install ignite-tools with command:

	./mvnw install -Pcheck-test-suites

	3) Run tests in the module:

	./mvnw test

	Apache RAT Instructions
	=======================
	To check license headers use:

	./mvnw clean validate -Pcheck-licenses

	For more information (e.g. exclude list) see "check-licenses" profile in "parent/pom.xml".


	Useful Release Commands
	=======================
	ZIP:
	zip -r9 apache-ignite-X.X.X-src.zip apache-ignite-X.X.X-src
	GPG:
	gpg --armor --output apache-ignite-X.X.X-src.zip.asc --detach-sig apache-ignite-X.X.X-src.zip