= JBoss Forge Contributing Guide

If you're looking for a development guide for Forge, first read https://github.com/forge/core/blob/master/README.asciidoc[this document].

== First Steps

=== Prerequisites

* Java 8+
* Maven 3.2.5+
* Git

=== Git Workflow

To contribute to Forge, fork the core repository to your own Git, clone your fork, commit your work on topic branches, and make pull requests.

If you don't have the Git client (`git`), get it from: <http://git-scm.com/>

Here are the steps in detail:

1. link:https://github.com/forge/core/fork[Fork] the project. This creates a the project in your own Git with the default remote name 'origin'.

2. Clone your fork. This creates and populates a directory in your local file system.

        git clone git@github.com:<your-username>/core.git

3. Add the remote `upstream` repository so you can fetch any changes to the original forked repository.

        git remote add upstream git@github.com:forge/core.git

4. Get the latest files from the `upstream` repository.

        git fetch upstream

5. Create a new topic branch to contain your features, changes, or fixes using the `git checkout -b  <topic-branch-name> upstream/master` command. For example:

        git checkout -b FORGE-123 upstream/master

6. Contribute new code or make changes to existing files. If you're using Eclipse, be sure to format your code using the provided https://raw.githubusercontent.com/forge/core/master/eclipse-code-formatter-profile.xml[Forge Code Formatter]). If you're using IntelliJ IDEA, we recommend using link:http://plugins.jetbrains.com/plugin/6546[this plugin] to use the before-mentioned Eclipse code formatter in IDEA.

7. Use the `git add` command to add new or changed file contents to the staging area.
        git add .

8. Use the git status command to view the status of the files in the directory and in the staging area and ensure that all modified files are properly staged:

        git status

9. Commit your changes to your local topic branch.

        git commit -m 'FORGE-XX: Description of change...'

10. If you made multiple commits, or if there were any merge commits created when you pulled from upstream, use rebase to squash them into a single commit, where 5 is the number of commits to rebase:

        git rebase -i HEAD~5

    Change 'pick' to 'f' for each commit you wish to fixup upwards. (If you do not change a line, it will not be modified.)

        1 pick ade2b1a FORGE-XX: Does something cool
        2 f c3ae0a2 almost done
        3 f c863bfb did more work
        4 f af793ae Started working on FORGE-XX
        5 pick 368bbb9 Previous commit written by someone else

    Once you are done, your commits should look like this:

        1 ade2b1a FORGE-XX: Does something cool
        2 368bbb9 Previous commit written by someone else

    You can view your commits by typing:

        git log

11. Push your local topic branch to your github forked repository. This will create a branch on your Git fork repository with the same name as your local topic branch name.

        git push origin HEAD

IMPORTANT: The above command assumes your remote repository is named 'origin'. You can verify your forked remote repository name using the command _git remote -v_.

12. Browse to the <topic-branch-name> branch on your forked Git repository and link:http://help.github.com/send-pull-requests/[open a Pull Request]. Give it a clear title and description.

== Building from source

Clone the repo (or your fork):
----
git clone git@github.com:forge/core.git
----
Use `https://github.com/forge/core.git` instead, if you do not have access, or clone the repo and use the fork's URL.

Build:
----
mvn clean install
----

TIP:: If you want to run the build without running all tests, use `mvn clean install -DskipTests`

The Forge 3 distribution will be present in the `dist/target` directory. Unzip and extract to get started:

----
unzip dist/target/forge-distribution-<release_version>-offline.zip -d ~
export FORGE_HOME=~/forge-distribution-<release_version>
export PATH=$FORGE_HOME/bin:$PATH
forge
----

=== Building the JBoss Tools plugins for Forge 3

JBoss Tools for Forge 3 will allow you to run Forge inside Eclipse. Build this only when you need to run Forge in Eclipse. The Forge-Core distribution is sufficient for the CLI mode.

Clone the repo (or your fork):
----
git clone git@github.com:jbosstools/jbosstools-forge.git
----

Include the https://github.com/jbosstools/jbosstools-devdoc/blob/master/building/how_to_build_jbosstools_4.adoc[required repositories in your settings.xml file], or copy the `settings.xml` from below and save it somewhere to use in the Maven build. This is also described in https://community.jboss.org/wiki/MavenGettingStarted-Developers:

[source,xml]
----
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
	<profiles>
		<profile>
		<id>jboss-default</id>
		<repositories>
		<!-- To resolve parent artifact -->
		<repository>
				<id>jboss-public-repository-group</id>
				<name>JBoss Public Repository Group</name>
				<url>http://repository.jboss.org/nexus/content/groups/public/</url>
			</repository>
			<repository>
				<id>jboss-snapshots-repository</id>
				<name>JBoss Snapshots Repository</name>
				<url>https://repository.jboss.org/nexus/content/repositories/snapshots/</url>
			</repository>
		</repositories>
		<pluginRepositories>
			<!-- To resolve parent artifact -->
			<pluginRepository>
				<id>jboss-public-repository-group</id>
				<name>JBoss Public Repository Group</name>
				<url>http://repository.jboss.org/nexus/content/groups/public/</url>
			</pluginRepository>
			<pluginRepository>
				<id>jboss-snapshots-repository</id>
				<name>JBoss Snapshots Repository</name>
				<url>https://repository.jboss.org/nexus/content/repositories/snapshots/</url>
			</pluginRepository>
		</pluginRepositories>
		</profile>
	</profiles>
	<activeProfiles>
		<activeProfile>jboss-default</activeProfile>
	</activeProfiles>
</settings>
----

=== Build:

----
mvn --settings ~/.m2/jbosstools.xml clean verify
----

The Forge artifacts from your local .m2 repository would be included in the JBoss Tools plugins for Forge. You can install them in an Eclipse Kepler installation, by adding `$JBOSSTOOLS_FORGE_DIR/site/target/forge.site-1.2.0-SNAPSHOT.zip` as an update site.

Note, you may need to run `git clean -fdx` to clean the target directories of older snapshot artifacts.

To use the Maven artifacts from the JBoss Nexus repository instead of your local .m2 repository, run:
----
mvn -U --settings ~/.m2/jbosstools.xml clean verify
----

=== Run:

This section applies when you do not wish to build and install the Eclipse plugin in an installation, but just work on the Forge sources and run it as an Eclipse application. This useful when you're working on the Forge sources instead of your own addons.

Import the following projects from the plugins/ module into your Eclipse workspace:

----
org.jboss.tools.aesh.core
org.jboss.tools.aesh.runtime
org.jboss.tools.aesh.ui
org.jboss.tools.forge.core
org.jboss.tools.forge.m2e
org.jboss.tools.forge.runtime
org.jboss.tools.forge.runtime.ext
org.jboss.tools.forge.ui
org.jboss.tools.forge.ui.notifications
----

Right-click the `org.jboss.tools.forge.ui project`, and choose Run As -> Eclipse Application. 

IMPORTANT: If you are unable to run the project as an Eclipse application, the reason is that you don't have the Tycho M2 Provider installed. If that's the case, install it via this update site: http://repository.tesla.io:8081/nexus/content/sites/m2e.extras/m2eclipse-tycho/0.7.0/N/0.7.0.201309291400/

Right click the `org.jboss.tools.forge.ui` project, choose Run As -> Run Configurations.. and set the VM arguments to: -Xmx1024m -XX:MaxPermSize=256m

== Choosing issues to work on

If you're wondering what issues would be suitable when you're just getting started, we recommend taking a look at link:https://issues.jboss.org/issues/?filter=12321213[the issues with the 'starter' label in our JIRA].

== License Information and Contributor Agreement

* JBoss Forge is licensed under the link:http://www.eclipse.org/legal/epl-v10.html[Eclipse Public License 1.0].
* There is no need to sign a contributor agreement to contribute to JBoss Forge. You just need to explicitly license any contribution under the EPL 1.0. If you add any new files to JBoss Forge, make sure to add the correct header.

=== Java,  Javascript and CSS files

      /**
       * Copyright 2016 Red Hat, Inc. and/or its affiliates.
       *
       * Licensed under the Eclipse Public License version 1.0, available at
       * http://www.eclipse.org/legal/epl-v10.html
       */

=== HTML, XML, XSD and XHTML files

      <!--
       ~ Copyright 2016 Red Hat, Inc. and/or its affiliates.
       ~
       ~ Licensed under the Eclipse Public License version 1.0, available at
       ~ http://www.eclipse.org/legal/epl-v10.html
      -->

=== Properties files and Bash Scripts

       # Copyright 2016 Red Hat, Inc. and/or its affiliates.
       #
       # Licensed under the Eclipse Public License version 1.0, available at
       # http://www.eclipse.org/legal/epl-v10.html

=== SQL files

      --
      -- Copyright 2016 Red Hat, Inc. and/or its affiliates.
      --
      -- Licensed under the Eclipse Public License version 1.0, available at
      -- http://www.eclipse.org/legal/epl-v10.html
      --

=== JSP files

----
<%--
Copyright 2016 Red Hat, Inc. and/or its affiliates.
   
Licensed under the Eclipse Public License version 1.0, available at
http://www.eclipse.org/legal/epl-v10.html
--%>
----

