<?xml version="1.0" encoding="UTF-8"?>
<!--

    Copyright (C) 2000 - 2024 Silverpeas

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or (at your option) any later version.

    As a special exception to the terms and conditions of version 3.0 of
    the GPL, you may redistribute this Program in connection with Free/Libre
    Open Source Software ("FLOSS") applications as described in Silverpeas's
    FLOSS exception.  You should have received a copy of the text describing
    the FLOSS exception, and it is also available here:
    "https://www.silverpeas.org/docs/core/legal/floss_exception.html"

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.

-->

<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Contributing to Silverpeas</title>
    <author>Emmanuel Hugonnet</author>
    <author>Miguel Moquillon</author>
  </properties>
  <head>
    <title>Contributing to Silverpeas</title>
  </head>
  <body>
    <section name="Git">
      <subsection name="What is git?">
        <p>
          <img src="../images/logos/logo_git.png" alt="git logo" style="height:30px;padding-right:10px;float:left;position:relative;" />
          <a href="http://git-scm.com/">Git</a> is a Distributed Version Control System (DVCS).
      The main difference with VCS is its distributed form, which means that
      there is not a single repository centralizing all the code history.
          <br/>All the code history is in each repository, which
      means that you have all the history in your local repository as well as in the others.
        </p>
        <p>
      Git works like the following figure:
        </p>
        <ul>
          <li>you add new or modified files and remove deleted files to your staging repository.</li>
          <li>when all your changes make sense you commit them to your local repository.</li>
          <li>now, you can share your modifications whith the rest of the world by pushing them to a remote repository.</li>
          <li>to get others' modifications pull or fetch them from a remote repository.</li>
        </ul>
        <p>
          <a href="../images/git_everthing_is_local.png">
            <img src="../images/git_everthing_is_local.png" alt="git workflow" style="height:404px;padding-left:100px;" />
          </a>
        </p>
        <p>For more information how to use Git, please visit the
          <a href="http://gitref.org/">Git Reference</a> web site.
        </p>
      </subsection>
      <subsection name="Why Git?">
        <p>Silverpeas is a free and libre project that values meritocracy.
          <em>In code we believe!</em>
          <br/>
      As we switched to the Git distributed source control system, we heavily blured the distinction between official project developers and external contributors.
      This makes it easier for you to:
        </p>
        <ul>
          <li>prepare changes, and for us to eventually merge them</li>
          <li>maintain your own private modifications of Silverpeas</li>
          <li>later split your own modifications and submit them back to us.</li>
        </ul>
      </subsection>
      <subsection name="Github">
        <p>
          <img src="../images/logos/logo_github.jpg" alt="github logo" style="height:40px;padding-right:10px;float:left;position:relative;" />
          Silverpeas's code is hosted on public Git repositories on GitHub, so that everybody can participate and contribute to the Silverpeas project.
          <br/>
          The Github features enhance the capabilities of a collaborative and distributed work.
        </p>
      </subsection>
    </section>
    <section name="How to contribute">
      <subsection name="Forking Silverpeas">
        <p>
          First, you have to
          <a href="https://docs.github.com/">create your account on Github</a>, then fork the
          <a href="https://github.com/Silverpeas">Silverpeas repositories</a> you are interested in.
        </p>
        <p>For information, Silverpeas is made up of the following projects, each of them with their
          own Git repository:</p>
        <ul>
          <li><a href="https://github.com/Silverpeas/silverpeas-dependencies-bom"><code>Silverpeas Dependencies</code></a> that
            is a global descriptor defining all the dependencies with their version and their scope required to build and to run
            Silverpeas. Usually, you won't have to modify this project.</li>
          <li><a href="https://github.com/Silverpeas/silverpeas-test-dependencies-bom"><code>Silverpeas Test Dependencies</code></a> that
            is a global descriptor defining all the dependencies with their version required to run the unit and integrations tests.
            Usually, you won't have to modify this project.</li>
          <li><a href="https://github.com/Silverpeas/Silverpeas-Project"><code>Silverpeas Project</code></a> that
          is a global descriptor for many of the Silverpeas projects: it imports the descriptors above and defines plugins and profiles to
            build Silverpeas according to different contexts. Usually, you won't have to modify this project.</li>
          <li><a href="https://github.com/Silverpeas/Silverpeas-Core"><code>Silverpeas Core</code></a> in which
          are defined the Core APIs of Silverpeas for both the business part and the Web part.</li>
          <li><a href="https://github.com/Silverpeas/Silverpeas-Components"><code>Silverpeas Components</code></a> that
          comprise all of the applications provided by Silverpeas (DEM, gallery, blog, ...)</li>
          <li><a href="https://github.com/Silverpeas/Silverpeas-Assembly"><code>Silverpeas Assembly</code></a> is
          a project that declares all the components that made up the Silverpeas collaborative platform and that
          defines the rules to build from them the final Silverpeas application, ready to be deployed into a JEE
          runtime.</li>
        </ul>
        <p>Once the fork completed, clone it:</p>
        <source>git clone URL_OF_THE_FORK</source>
        <p>Your fork is then referenced by your git configuration with the name <code>origin</code></p>
        <p>
          In order to keep your fork up-to-date, you will have to pull modifications from the Silverpeas repository. Thus, you
          have to add a remote repository to your git configuration linking your local repository to the Silverpeas one. The
          recommended name (used afterwards in he documentation) is
          <code>silverpeas</code>.
          <br/>
          To add a remote repository to your local, execute the following command:
        </p>
        <source>git remote add silverpeas URL_OF_SILVERPEAS_REPOSITORY</source>
        <p>For example:</p>
        <source>git remote add silverpeas git@github.com:Silverpeas/Silverpeas-Core.git</source>
        <p>To synchronize your local repository with Silverpeas, we recommend to execute the following command:</p>
        <source>git pull --rebase silverpeas master</source>
        <p>Or to be less confusing by unexpected merge conflicts, you can divide the synchronization in two steps:</p>
        <source>git fetch silverpeas master
git rebase FETCH_HEAD</source>
        <p>The <code>rebase</code> operation while synchronizing your local repository with Silverpeas is to ensure
        your changes will be on top of the fetched modifications and hence they won't be mixed with external commits.
        By doing this, when we'll merge your changes, the history of Silverpeas changes will be clean and understandable.</p>
      </subsection>
      <subsection name="Build Silverpeas">
        <p>We use the <a href="https://www.oracle.com/java/technologies/downloads/#java11">Java Development Kit 11</a> (Oracle JDK or OpenJDK 11)
          and the <a href="http://maven.apache.org/">maven build tool</a> to manage the build life-cycle of our projects. With Maven,
          a project is described by a POM (Project Object Model) that is defined in the <code>pom.xml</code> file at the root of the
          project. Maven provides at least the following features:</p>
        <ul>
          <li>a predefined directories layout for both sources code and build results,</li>
          <li>a build workflow in which each stages are well defined,</li>
          <li>a dependency management by using both a local and a remote repository in which the dependencies (named artifacts) are available.</li>
        </ul>
        <p>Before building your copy of a Silverpeas project, you have to define some settings to Maven like indicating
          our own <a href="https://www.silverpeas.org/nexus">Maven repository</a>. For doing, please edit a file <code>settings.xml</code>
          in the <code>.m2</code> directory at your home folder and add the following lines:</p>
        <source>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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
                      https://maven.apache.org/xsd/settings-1.0.0.xsd"&gt;
  &lt;mirrors&gt;
    &lt;mirror&gt;
      &lt;id&gt;silverpeas&lt;/id&gt;
      &lt;mirrorOf&gt;*&lt;/mirrorOf&gt;
      &lt;url&gt;https://www.silverpeas.org/nexus/content/groups/silverpeas/&lt;/url&gt;
    &lt;/mirror&gt;
  &lt;/mirrors&gt;

  <!-- And in the case of being behind a given proxy
  &lt;proxies&gt;
   &lt;proxy&gt;
      &lt;active&gt;true&lt;/active&gt;
      &lt;protocol&gt;http&lt;/protocol&gt;
      &lt;host&gt;proxy.somewhere.com&lt;/host&gt;
      &lt;port&gt;8080<&lt;port&gt;
      &lt;username&gt;proxyuser&lt;/username&gt;
      &lt;password&gt;somepassword&lt;/password&gt;
      &lt;nonProxyHosts>www.google.com|*.somewhere.com&lt;/nonProxyHosts&gt;
    &lt;/proxy&gt;
  &lt;/proxies&gt;
  -->
&lt;/settings&gt;
        </source>
        <p>Once done, you are ready to build the project:</p>
        <source>mvn clean install</source>
        <p>or without running the tests:</p>
        <source>mvn clean install -Dmaven.test.skip=true</source>
        <p>In order to build the Silverpeas application,
          you have to build first <code>Silverpeas-Core</code> and then <code>Silverpeas-Components</code>.
          If you have modified <code>silverpeas-dependencies-bom</code>, <code>silverpeas-test-dependencies-bom</code>,
        <code>Silverpeas-Project</code>, you have to compile first this project before anything.</p>
        <p>In the case you have added a new application, you can reference it into the <code>POM</code>
        of the <code>Silverpeas-Assembly</code> project.</p>

      </subsection>
      <subsection name="Installing and testing your codes">
        <p>Beside the unit and integration tests, you can test functionally your code in Silverpeas by
        installing it with your changes.</p>
        <p>The project <code>Silverpeas-Distribution</code> is the source code to generate the
          Silverpeas installation archives for both Windows and Unix-like systems. You can also build it
          by executing the following command:</p>
        <source>mvn clean package</source>
        <p>and the archives will be generated into the <code>target</code> directory of the project.
        Then just extract it, set correctly the environment variables <code>SILVERPEAS_HOME</code>
        and <code>JBOSS_HOME</code> and follows the instructions in the
          <a href="../installation/installationV6.html">Silverpeas installation page</a>.</p>
        <p>Once done, you are ready to run Silverpeas either in debugging mode or in a normal mode
        to test it. For doing, go to the folder <code>SILVERPEAS_HOME/bin</code> directory and then:</p>
        <source>./silverpeas clean install</source>
        <p>to clean any previous installation of Silverpeas and install your own changes,</p>
        <source>./silverpeas start</source>
        <p>to run Silverpeas in normal mode,</p>
        <source>./silverpeas debug</source>
        <p>to run Silverpeas in debugging mode,</p>
        <source>./silverpeas stop</source>
        <p>to stop Silverpeas.</p>
      </subsection>
      <subsection name="Creating a development branch">
        <p>Now that you have your own repository, let's create a branch to develop some code in it.
        The branch name should reflect the development feature or bug you are working on. It exists
        two main ways to handle the local and remote branchs with Gits.
        </p>
        <p>The first approach is to create the branch in local, then pushes it to the fork and sets the local branch to track the remote one:</p>
        <source>git branch BRANCH_NAME
git push origin BRANCH_NAME
git branch --set-upstream BRANCH_NAME origin/BRANCH_NAME</source>
        <p>The second approach is to create the branch in your fork, then creates from it a local branch that will also track it:</p>
        <source>git push origin master:refs/heads/BRANCH_NAME
git branch --track BRANCH_NAME origin/BRANCH_NAME</source>
        <p>or to create remotely a branch from another one:</p>
        <source>git push origin EXISTING_BRANCH:refs/heads/BRANCH_NAME
git branch --track BRANCH_NAME origin/BRANCH_NAME</source>
        <p>Now you can switch your working directory to the branch you have created (id est checkout the branch):</p>
        <source>git checkout  BRANCH_NAME</source>
        <p>When all your modifications are commited, it is time to push them to your remote branch.</p>
        <source>git push</source>
      </subsection>
      <subsection name="Integrating your changes in Silverpeas">
        <p>Now that your development is ended, you may want to integrate it into Silverpeas.
          <br/>
        To do this we take advantage of
          <a href="http://help.github.com/pull-requests/">Github's "Pull Request" feature</a>.
        </p>
        <p>On receiving your pull request, the Silverpeas core team will look into it and may give you some remarks.
          <br/>
        When your code is accepted it will be merged into Silverpeas master branch and you will be informed of this.
          <br/>
        Don't forget to synchronize both your repository and your fork with Silverpeas's in order to be up to date. We'll be pleased that you do it before any pull requests.
        </p>
        <source>git checkout master
git pull silverpeas master
git push
        </source>
        <p>Your development branches for the integrated code are now obsolete, so you may want to delete them.</p>
        <source>git push origin :BRANCH_NAME
git branch -D BRANCH_NAME</source>
      </subsection>
    </section>
  </body>
</document>
