http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/cplusplus-coding-guidelines.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/cplusplus-coding-guidelines.md b/docs/src/site/markdown/cplusplus-coding-guidelines.md deleted file mode 100644 index 3470641..0000000 --- a/docs/src/site/markdown/cplusplus-coding-guidelines.md +++ /dev/null @@ -1,310 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> - -These are the C++ coding guidelines that are part of the acceptance criteria for code submitted to the Trafodion. Trafodion reviewers use these guidelines when reviewing changes. - -The guidelines describe practices that are either required or preferred. In addition, areas where there is no preference between two or more practices are described. - -Trafodion is composed of several distinct sub-projects, some of which have coding guidelines that differ from the Trafodion standard; for example, a requirement in most areas of the code may be only preferred in others. - -There may also be existing code that violates one or more of the published requirements. The intent is to correct these over time, and corrections are encouraged when changing code to make a fix or implement new functionality. However, changes that are solely coding guideline changes are not recommended since this places undue burden on the reviewers. - -# Header Files -Keep **<code>#include</code>** directives to a minimum in header files. - -You may forward declare classes and structs when the only use within the header file is a pointer or reference. While includes should be kept to a minimum, if something is used in a header file and cannot be forward declared, it must be explicitly included. - -All files, headers and implementation, should include everything they need to be self-sufficient. They should never assume something will be pre-included. In other words, the contents of a header file should compile cleanly by itself. To help ensure this, all implementation files should include their respective header file first. - -Header files should not contain declarations for public items that are only used by the implementation file. Public items that are require in the implementation file but not the header file should be declared in the implementation file. The preference is NOT to create header files that consist only of includes of other header files. - -Declare as little as possible in the header file and keep as much of the actual implementation private as is reasonable. For instance, donât include in a header file declarations of types, enums, and functions that are only referenced by the implementation file. - -## Including Standard Header Files -The preference is for C++ style includes over C style includes for standard header files. - - //Preferred - #include <cstdio> - //Accepted - #include <stdio.h> - -## Include Guards -All header files must use include guards. The name of the include guard **<code>#define</code>** should be the filename in all uppercase, with underscore used in place of periods. - -For instance, if the header file is named **<code>ServerInterface_ODBC.h</code>**, the header file should begin and end as follows: - - #ifndef SERVERINTERFACE_ODBC_H - #define SERVERINTERFACE_ODBC_H - ... - #endif /* SERVERINTERFACE_ODBC_H */ - -Comments following the **<code>#endif</code>** indicating the include guard are preferred. - -# Variable Declaration and Naming Standards -Trafodion uses a combination of Pascal and Camel case. - -* Pascal case means that the first letter in each word in an identifier is capitalized. -* Camel case is similar except the first letter is in lower case. - -For both, underscores are **not** used to separate words. The general rule is that identifiers with local scope start with a lower case letter and identifiers with global scope start with an upper case letter. - - //Pascal case - class AuthenticationMessage; - //Camel case (aka lower Camel case or camelCase) - int logonCount; - Class Names - -Class names should be Pascal case and should describe the object contents (not what it does), with as little abbreviation as possible. When names include acronyms, the acronyms should be in all upper case. - -**Acceptable Examples** - - //Preferred - - class SQLSessionContext; // an object that contains the context for a SQL session - class PrivilegeList; // a list of privileges - -**Poor Examples** - - class OutputInfo; // Doesnât describe class contents, no context - class ReadTableDef; // Describes what class does, not contents - class Cmdline_Args; // Prefer Pascal case, no underscore, for class names - -## Class Member Variable Names -Private member data variables should be suffixed with an underscore and should use Camel case. When names include acronyms, the acronyms should be in all upper or all lower case, dependent on which case the first letter should be. - -**Example** - - class Employee - { - public: - Employee (); - private: - std::string firstName_; - std::string lastName_; - uint16_t departmentNumber_; - std::string departmentName_; - uint32_t irsSSN_; - } - -## Function Names -Class member functions and static file functions should use Camel case. External non-class functions should use Pascal case. Except for constructors, destructors, and operators, the function name should include a verb that describes the action the function is performing. - -**Good Examples** - - //Class member functions - int32_t getSalary() const; - int32_t setAuthID(); - int32_t closeAllCursors(); - -**Bad Examples** - - // Is it setting break enabled, returning it or ??? - int32_t SQLCLI_BreakEnabled(); - -## Enums -Enum types should use Pascal case and describe the class of enums. If the enum is declared outside of a class, the type name should include an indication of the scope of the enums. - -Enums themselves should be declared as all upper case. The names may begin with a common prefix or be independent, depending on the usage. - -When enums represent an arbitrary set of return values (that is, error codes, state codes, etc.), then avoid the values -1, 0, and 1 if using weakly typed enums, to reduce the chance of matches with Booleans or uninitialized variables. - -The preference is to declare enums as strongly typed. - - enum class EnumName {...}; - -## Boolean Variables -Boolean variables names should include a verb, state, and optionally a noun (object whose state is in question) indicating the nature of the Boolean. Any combination is acceptable, however verbState is the most common. - -**Good Examples** - - bool isValid; // verbState - bool isValidTable; // verbStateNoun - bool tableIsDroppable; // nounVerbState - bool hasData; // verbState - -**Bad Examples** - - bool valid; - bool tableState; - bool empty; - -Functions that return a Boolean should also have names of the form verbState or verbStateNoun if the functions return state information. (This naming standard does not apply to functions returning Boolean as indication of success or failure.) - -**Good Examples** - - bool isValidHbaseName(); - bool isHostNameExcluded(); - bool canUseCbServer(); - -**Bad Examples** - - // Donât use get for Boolean accessors - bool getUDRAccessModeViolation(); - - // Donât use integer return for Boolean functions - short existsInHBase(); - - // Function name implies it is sending settings to the compiler, but it is - // actually only returning an indication that settings should be sent. - // A better name would be shouldSendSettingsToCompiler(). - bool sendSettingsToCompiler(); - -Parts of Trafodion code use one of two Boolean typedefs, **<code>NABoolean</code>** and **<code>ComBoolean</code>**, declared as follows: - - typedef int Int32; - typedef Int32 NABoolean; - typedef NABoolean ComBoolean; - const NABoolean TRUE = (1 == 1); - const NABoolean FALSE = (0 == 1); - -Exercise care when mixing usage of bool and **<code>NABoolean</code>**/**<code>ComBoolean</code>** types, as the latter are not guaranteed to only contain values of TRUE and FALSE. The use of non-standard Boolean types is gradually being phased out. - -## Constants -All constant names should be all upper case, regardless of how the constant is declared. That is, enums, defines, and variables with the **<code>const</code>** modifier should be named in all upper case. - -Defines, enums, and const are all permitted and used throughout Trafodion, although most code in Trafodion uses enum for numerical constants and defines for character constants. - -For new code, the use of const char or string is preferred for character constants instead of defines. - -## Namespace Names -The preference is for namespaces to be all lower case, with preference to single words (note the exception to the rule that a name with global scope should start with an upper case). - -If a namespace must be dual-worded, use underscores. If mixed case names are used, Pascal case is preferred. - -**Examples** - - //Preferred - - namespace compiler - //Accepted - - namespace Compiler - -# Indentation and Formatting -## Indentation -TAB characters are not permitted in source files except for text files (for example, makefiles) that require them. - -Trafodion code uses several indenting depths, including 2, 3, 4, and 8 spaces. Most common is 2 and 3. - -Use the style found in existing code, and when writing new code, use either 2, 3, or 4, and remain consistent. - -A variety of control block indentation styles are used throughout Trafodion, most commonly Allman, Whitesmith, Stroustrup, and GNU. Follow the predominant style when making small to medium changes to existing code. For new code, the Allman style is preferred. - - //Allman - if (x > 5) - { - error = doThis(x); - if (error != 0) - { - return false; - } - } - else - { - doThat(x); - } - - //Whitesmith - if (x > 5) - { - error = doThis(x); - if (error != 0) - { - return false; - } - } - else - { - doThat(x); - } - - //Stroustrup - if (x > 5) { - error = doThis(x); - if (error != 0) { - return false; - } - } - else { - doThat(x); - } - -Note that the Stroustrup and the similar K&R formats were popularized by usage in books where conservation of line count was a goal. - - //GNU - if (x > 5) - { - error = doThis(x); - if (error != 0) - { - return false; - } - } - else - { - doThat(x); - } - -# Comments -## Comment Style -C++ style comments are preferred, but C comments are acceptable as well. - -Some code uses Doxygen style comments, but this is not required. - -## When/Where Comments Should Be Used -Every file should have a comment at the beginning describing the purpose of the file. - -In header files where classes are declared, there should be a comment describing the class, including purpose and usage. Also describe anything out of the ordinary, such as the use of multiple inheritance. - -Within implementation files, in addition to the comment at the beginning of the file, add comments for any global or static variables defined in the file, and how the variable is handled in a multi-threaded environment (if applicable). - -Also, for each function defined, describe the purpose and intent of the function. For each parameter, list whether it is input or output (or both), how it is used, and any range restrictions imposed. For functions not returning void, describe the possible return values. - -Within the body of the function, there is no need to write comments that document the obvious. But if there is any complexity to the logic, at a minimum document the intent, and consider documenting the details (assumptions, limits, unexpected side effects from function calls, etc.) - -If a feature is only partially implemented, add a comment indicating at a high level what work remains. Prefix the comment with //TODO. - - //TODO Code is currently not thread safe. Need to protect allocation of ... - -# Error Handling -## Asserts -Trafodion uses asserts in the "debug" build. Use asserts freely, but ensure they do not contain any side effects as the code is not present in the "release" build. - -## Error Return/Retrieval -Avoid the use of integer return codes for success and error codes. Instead, use bool for simple succeeded/failed and enum types for returns with multiple conditions. - -## Exception Handling -Trafodion code mixes usage of exceptions and error returns. When using try/catch blocks, keep the scope as small as possible. Ensure all exceptions thrown are handled, potentially in main() if nowhere else. - -# General Guidelines -## Casting -Avoid using C-style casts. Use C++-style casts instead, as they are often safer and easier to search for. - - //Preferred - - int x = static_cast<int>(shortVariable); - - MyType *myVar = reinterpret_cast<MyType *>(voidPtr); - -Donât blindly cast to remove a compiler error or warning. Ensure the cast is safe. - -Use const casting sparingly. Often the use of mutable or changing a function to be const correct is a better solution. - -## Types -Use standard types defined in **<code>\<cstdint\></code>** or **<code>\<stdint.h\></code>**. Note that Trafodion defines and uses many non-standard types (for example, **<code>Int32</code>**, **<code>Lng32</code>**), but this usage is being phased out. - -Use types with explicit sizes (for example, **<code>int32_t</code>**, **<code>int64_t</code>**) when size is a factor in the code, such as an external API, or column in a table. - -Where size is not a factor (counters, indexes) a non-sized type such as **<code>int</code>** or **<code>long</code>** may be used. However, in general, **<code>size_t</code>** and **<code>ssize_t</code>** are preferred for variables where fixed size is not required. \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/create-dev-environment.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/create-dev-environment.md b/docs/src/site/markdown/create-dev-environment.md deleted file mode 100644 index 5e5e955..0000000 --- a/docs/src/site/markdown/create-dev-environment.md +++ /dev/null @@ -1,154 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how to create the test environment used for Trafodion development, which is intended for people that are contributing to the Trafodion source tree. Please refer to [Download](download.html) if you want to try the Trafodion product environment. - -# Prerequisites -The following prerequisites need to be met in order to create a functional Trafodion test environment. - -## Passwordless ```ssh``` -Check to see if you have passwordless SSH setup correctly. - - ssh localhost - Last login: Fri Nov 6 22:44:00 2015 from 192.168.1.9 - -If the **```ssh localhost```** command prompts for a password, then passwordless **```ssh```** is not set up correctly. - -The following is an example of setting up passwordless **```ssh```** using **```id_rsa```** keys. You can choose the method that best represents your environment. - -If you already have an existing set of **```ssh```** keys. Simply copy both the **```id_rsa.pub```** and **```id_rsa```** to your **```~/.ssh```** directory. - -Then, do the following to modify your **```ssh```** environment. - - cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys - chmod 600 ~/.ssh/id_rsa - echo "NoHostAuthenticationForLocalhost=yes" >>~/.ssh/config - chmod go-w ~/.ssh/config - chmod 755 ~/.ssh; chmod 640 ~/.ssh/authorized_keys; cd ~/.ssh; chmod 700 .. - -If you need to create your keys first, then do the following. - - rm -rf ~/.ssh - ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa - cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys - chmod 600 ~/.ssh/id_rsa.pub - echo "NoHostAuthenticationForLocalhost=yes" >>~/.ssh/config - chmod go-w ~/.ssh/config - chmod 755 ~/.ssh; chmod 640 ~/.ssh/authorized_keys; cd ~/.ssh; chmod 700 .. - -## System Limits -Please check that the system limits in your environment are appropriate for Apache Trafodion. If they are not, then you will need to increase the limits or Trafodion cannot start. - -The recommended settings are as follows. - - $ ulimit âa - core file size (blocks, -c) 1000000 - data seg size (kbytes, -d) unlimited - scheduling priority (-e) 0 - file size (blocks, -f) unlimited - pending signals (-i) 515196 - max locked memory (kbytes, -l) 49595556 - max memory size (kbytes, -m) unlimited - open files (-n) 32000 - pipe size (512 bytes, -p) 8 - POSIX message queues (bytes, -q) 819200 - real-time priority (-r) 0 - stack size (kbytes, -s) 10240 - cpu time (seconds, -t) unlimited - max user processes (-u) 267263 - virtual memory (kbytes, -v) unlimited - file locks (-x) unlimited - -Please refer to this [article](http://www.itworld.com/article/2693414/setting-limits-with-ulimit.html) for information on how you change system limits. - -# Setup -You can create a Trafodion test environment using a: - -* **Pre-Installed Hadoop**: Trafodion installation on a system that already has a compatible version of Hadoop installed -* **Local Hadoop**: You install a Hadoop environment using the **```install_local_hadoop```** script - -Your installation approach depends on whether you already have installed Hadoop. - -## Pre-Installed Hadoop -Use the following instructions if you're installing Trafodion on a pre-installed Hadoop environment. -### Build Binary tar Files -Build the Trafodion binary tar files. - - cd <Trafodion source directory> - make package - -### Install Trafodion -Please refer to the installation instructions described in the [Installation](install.html) page. - -## Local Hadoop -Use the following instructions if you need to install a local Hadoop environment. -### Run ```install_local_hadoop``` -The **```install_local_hadoop```** script downloads compatible versions of Hadoop, HBase, Hive, and MySQL. Then, it starts Trafodion. - -<div class="alert alert-dismissible alert-info"> - <button type="button" class="close" data-dismiss="alert">&close;</button> - <p style="color:black"><strong>Time Saver</strong></p> - <p style="color:black"><strong>```install_local_hadoop```</strong> downloads Hadoop, HBase, Hive, and MySql jar files from the Internet. To avoid this overhead, you can download the required files into a separate directory and set the environment variable <strong>```MY_LOCAL_SW_DIST```</strong> to point to this directory.</p> -</div> - -Command | Usage ------------------------------------------------|-------------------------------------------------------- -**```install_local_hadoop```** | Uses default ports for all services. -**```install_local_hadoop -p fromDisplay```** | Start Hadoop with a port number range determined from the DISPLAY environment variable. -**```install_local_hadoop -p rand```** | Start with any random port number range between 9000 and 49000. -**```install_local_hadoop -p <port>```** | Start with the specified port number. - -For a list of ports that get configured and their default values, please refer to [Port Assignments](port-assignment.html). - -### Sample Procedure -Start a new **```ssh```** session and ensure that the Trafodion environmental variables are loaded. - - cd <Trafodion source directory> - source ./env.sh - -Install the Hadoop software. - - cd $MY_SQROOT/sql/scripts - install_local_hadoop - ./install_traf_components - -Verify installation. - - $ swstatus - 6 java servers and 2 mysqld processes are running - 713 NameNode - 19513 HMaster - 1003 SecondaryNameNode - 838 DataNode - 1173 ResourceManager - 1298 NodeManager - -Six java servers as shown above and two mysqld processes should be running. - -# Install and Build Trafodion -Please refer to [Modify Code](code.html) for information on how to install and build Trafodion from its source code. - -# New Source Download -You need to do the following each time you download new source code. - - cd <Trafodion source directory> - source ./env.sh - cd $MY_SQROOT/etc - # delete ms.env, if it exists - rm ms.env - cd $MY_SQROOT/sql/scripts - sqgen - -# Manage -Please refer to [Manage Development Environment](manage-dev-environment.html) for instructions. http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/develop.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/develop.md b/docs/src/site/markdown/develop.md deleted file mode 100644 index fa4680f..0000000 --- a/docs/src/site/markdown/develop.md +++ /dev/null @@ -1,253 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how to help develop the Trafodion source tree. Please refer to the [Contribute](contribute.html) page for information about other ways to contribute to the Trafodion project. - -# Prerequisites -You need to register as a Trafodion contributor before you can help us develop Trafodion. Please perform the following registration actions: - -<table> - <tr> - <th style="width:30%;">Area</th> - <th style="width:55%;">Notes</th> - <th style="width:15%;">URL</th> - </tr> - <tr> - <td><strong>Individual Contributor License Agreement (ICLA)</strong></td> - <td>You should sign the ICLA before contributing content to the Trafodion source tree. (Required to become a committer.)</td> - <td><a href="https://www.apache.org/licenses/icla.txt";>ICLA Agreement</a><br /> - <a href="http://www.apache.org/licenses/";>Approval Process</a> - </td> - </tr> - <tr> - <td><strong>Source Control</strong></td> - <td>You must have a git account in order to contribute to the Trafodion source. If you haven't already done so, please join git.</td> - <td><a href="https://github.com/join";>Git Signup</a></td> - </tr> - <tr> - <td><strong>Defect Tracking</strong></td> - <td>In order to have certain permissions, including assigning issues to yourself, you need to be a Contributor in the project. Be sure to sign up for a JIRA account if you don't have one.</td> - <td><a href="https://issues.apache.org/jira/secure/Signup!default.jspa";>Jira Signup</a></td> - </tr> -</table> - -Please send an e-mail to the [Trafodion development list](mail-lists.html) with the approved ICLA attached. Include your git and Jira IDs. - -Wait for the response and then you're ready to help us develop Trafodion. - -# Development Environment -You use the following tools and guidelines to develop Trafodion: - -<table> - <body> - <tr> - <th style="width:15%;">Area</th> - <th style="width:15%;">Tool</th> - <th style="width:55%;">Notes</th> - <th style="width:15%;">Location</th> - </tr> - <tr> - <td><strong>Trafodion Architecture</strong></td> - <td>Document</td> - <td>Please review the Trafodion architecture to ensure that you understand how the different components related to each other.</td> - <td><a href="architecture-overview.html">Trafodion Architecture</a></td> - </tr> - <tr> - <td><strong>Defect Tracking</strong></td> - <td>Jira</td> - <td>View all the Trafodion defects and enhancements requests in the Jira system hosted by Apache.</td> - <td><a href="https://issues.apache.org/jira/browse/TRAFODION";>Trafodion Jiras</a></td> - </tr> - <tr> - <td><strong>Defect Management</strong></td> - <td>Document</td> - <td>Please read about our approach to defect management. Mostly, any changes you'll make will be in response to a defect reported in Jira.</td> - <td><a href="defect-management.html">Defect Management (TBD)</a></td> - </tr> - <tr> - <td><strong>Git Tools</strong></td> - <td>git</td> - <td><p>Most of the Trafodion development is done on Linux. Development of the web site and/or documentation can successfully be done on Windows.</p><p>Please download the appropriate tool version; Linux or Windows.</p><p>Then, please refer to <a href="https://help.github.com/articles/set-up-git/";>GitHub Documentation</a> for information on how to set up your git environment. Ensure that you register your <a href="https://github.com/settings/ssh";>ssh keys</a>.</p></td> - <td><a href="http://git-scm.com/downloads";>Download git</a></td> - </tr> - <tr> - <td><strong>Code Repository</strong></td> - <td>git</td> - <td>The full Trafodion source tree can be retrieved from either of these repositories.</td> - <td><a href="https://git-wip-us.apache.org/repos/asf/incubator-trafodion.git";>Apache Repository</a><br /><a href="https://github.com/apache/incubator-trafodion";>GitHub Mirror</a> - </td> - <tr> - </tr> - <td><strong>Code Organization</strong></td> - <td>Document</td> - <td>Please familiarize yourself with the Trafodion code organization.</td> - <td><a href="code-organization.html">Code Organization</a></td> - </tr> - <tr> - <td><strong>C++ Coding Guidelines</strong></td> - <td>Document</td> - <td>Please read the coding guidelines for the Trafodion C++ code before making changes.</td> - <td><a href="cplusplus-coding-guidelines.html">C++ Coding Guidelines</a></td> - </tr> - <tr> - <td><strong>Debugging Tips</strong></td> - <td>Document</td> - <td>Documented tips describing how to debug your code in unit testing.</td> - <td><a href="debugging-tips.html">Debugging Tips (TBD)</a></td> - </tr> - <tr> - <td><strong>Testing</strong></td> - <td>Document</td> - <td>Trafodion has a rich set of test suites for each of its components. You'll need to run the tests before submitting a code change for review.</td> - <td><a href="testing.html">How to Test</a></td> - </tr> - <tr> - <td><strong>Code Reviews</strong></td> - <td>git</td> - <td> - <p>We use GitHub pull-requests for code review. All of the activity on github is captured in ASF JIRA and/or ASF project mail archives by ASF INFRA team automation. In this way, we do not depend on github for accurate history of where contributions come from.</p> - <p>Each pull-request title should start with a JIRA ID in brackets, so that activity can be logged to the correct JIRA issue.</p> - <p>Regardless of the title, the pull-request activity is also logged to the <a href="http://mail-archives.apache.org/mod_mbox/incubator-trafodion-codereview/";>code-review mail list</a>.</p> - </td> - <td><a href="https://github.com/apache/incubator-trafodion/pulls";>Current Pull Requests</a></td> - </tr> - </body> -</table> - -# Initial Setup -This set of tasks is performed **after** downloading the git tools. Refer to [Development Environment](#development_environment) above. - -You should not have to perform these tasks more than once. - -## Setting Up the Git Enviroment -If you have not done so already, now is the time to set up your **<code>git</code>** environment. Refer to the [GitHub Documentation](https://help.github.com/articles/set-up-git/) for information on how to set up your Git environment. Please ensure that you register your [ssh keys](https://github.com/settings/ssh). - -## Fork the Trafodion Repository -You create a private fork of Trafodion on <https://github.com/apache/incubator-trafodion>. Use the **fork** button top-right on the page to create your fork, which will be named **\<your-git-id\>_fork.** - -The following examples use **trafdeveloper** to represent **\<your-git-id\>**. - -## Clone the Trafodion Repository -Use the **git shell** to perform this task. - - # Move to the directory where you want to install the Trafodion source code. - cd mysource - # Clone the Trafodion source code - git clone git://git.apache.org/incubator-trafodion.git - # Register your fork as a remote branch - git remote add trafdeveloper_fork [email protected]:trafdeveloper/incubator-trafodion - -At this point, you've finished all preparation steps. Now, you can start making changes. - -# Making Changes -## Create a Task Branch -You create a task branch to make changes to the Trafodion source. Typically, we name the branches after the Jira we are working on. In this example, the Jira is: **TRAFODION-1507**. - - # Ensure that you have the latest changes - git fetch --all - # Checkout source - git checkout -b TRAFODION-1507 origin/master - -<table><tr><td> - <p><strong>Note</strong></p> - <p>The source tar file has been signed with pgp key A44C5A05, which is included in the download location's - <a href="https://dist.apache.org/repos/dist/release/incubator/trafodion/KEYS";>KEYS file</a> - </p> -</td></tr></table> - - -## Change Recipes -The procedure to make changes depends on what type of problem or feature you're working on. - -Change Type | Refer To ----------------------------------|------------------------------------------------------------ -**Code** | [Modify Code](code.html) -**Documentation** | [Modify Documentation](document.html) -**QA Tests** | [Modify Tests](tests.html) -**Web Site** | [Modify Web Site](website.html) - -## Commit Changes - -<div class="alert alert-dismissible alert-info"> - <button type="button" class="close" data-dismiss="alert">&close;</button> - <p style="color:black"><strong>Reminder</strong></p> - <p style="color:black">If making code changes: please ensure that you run the <a href="testing.html">Regression Tests</a> before committing changes.</p> -</div> - -Perform the following steps to commit your changes. - - # Commit changes - git commit -a - # Dry-run check - git push -n trafdeveloper_fork HEAD - # Push changes to your private fork - git push trafdeveloper_fork TRAFODION-1507 - -## Create Pull Request -Your changed code needs to be reviewed by a Trafodion committer. Therefore, you need to create a pull request for your private repositoryc. - - # Generate pull request - git pull-request - -Ensure that you include the Jira ID at the beginning of the title in your pull request. For example: - - [TRAFODION-1507] Explanation of the changes you made. - -[Automated Tests](#automated_tests) are normally triggered to run on every pull request. If you have modified the documentation or the web site, then you can skip the automated testing by adding the following phrase to the comments of the pull request: - - jenkins, skip test - -## Review Comments -The pull request gets reviewed by the committers and once you get a consensus, then the committer merges your changes into the main incubator-trafodion branch. - -## Address Review Comments -Follow the GitHub conversation on your pull request (you should be automatically subscribed). Respond to questions and issues. - -If you need to make additional changes, then do the following: - -1. Check out the code: **<code>git checkout TRAFODION-1507</code>** -2. Make the requested changes. -3. Run regression tests. -4. Commit the changes: **<code>git commit -a</code>** -5. Push the changes back to your private git fork: **<code>git push trafdeveloper_fork TRAFODION-1507</code>** - -## Merge Changes -If all is well, a committer will merge your change into the Apache repository, which is mirrored on github. - -You may be asked to close out the JIRA or other follow up. - -Your change is done. Thanks for your contribution to Trafodion. - -# Automated Tests -Automated tests take several hours to complete from when your pull-request was approved by a committer or updated with a new commit. - -Normally, the Traf-Jenkins user will post a message in the pull-request with a link to the results. You can also check the Jenkins server to see the status even before the tests are finished. Look in the **Build History** table for the build/test job that matches your pull-request. For example, the master branch tests are located at: <https://jenkins.esgyn.com/job/Check-PR-master/> - -## Reviewing Logs - -There are two approaches to reviewing logs. - -### Approach 1 - -* The first two columns in build-job table are links to the specific sub-job. Clicl on the link to drill down. -* The console log of each job has a link to the log file directories (close to the top). Look for **Detailed logs**. - -### Approach 2 - -* Go to: <http://traf-logs.esgyn.com/PullReq/> -* Click on the number of the pull request. The next directory level is the build number. With multiple commits or re-tests, it is possible for a pull request to have multiple builds. -* Under the build number is a directory for each specific job. Example: <http://traf-logs.esgyn.com/PullReq/18/35/regress-seabase-ahw2.2/> - -## More Information -The check tests do not include all of the automated daily tests. If you (or another contributor) want, you can run additional tests on the pull request. Refer [automated test setup (TBD)](automated-tests.html) for more information. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/document.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/document.md b/docs/src/site/markdown/document.md deleted file mode 100644 index c566cae..0000000 --- a/docs/src/site/markdown/document.md +++ /dev/null @@ -1,143 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expreess or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how to modify the Trafodion documentation. Please refer to the [Contribute](contribute.html) page for information about other ways to contribute to the Trafodion project. - -# Source -Documents do **not** include version information as part of the file name. - -## Source Location - -Document | Source Format | Source Tree | Output Format ---------------------------|-----------------------|------------------------------------------------|---------------------------- -Client Installation Guide | asciidoc | ```docs/client_install/``` | Web Book, PDF -Command Interface Guide | asciidoc | ```docs/comand_interface/``` | Web Book, PDF -DCS Reference Guide | asciidoc | ```dcs/src/main/asciidoc/``` | Web Book -DCS APIs | javadoc | ```dcs/src/main/java/``` | Web Book -odb User Guide | asciidoc | ```docs/odb/``` | Web Book, PDF -REST Reference Guide | asciidoc | ```core/rest/src/main/asciidoc/``` | Web Book -REST APIs | javadoc | ```core/rest/src/main/java/``` | Web Book -SQL Reference Manual | asciidoc | ```/docs/sql_reference/``` | Web Book, PDF - -## Source Tree Organization - -### DCS and REST - -### All Other -All other documents share a common web-book stylesheet definition, which is located in **```docs/css/trafodion-manuals.css```**. - -The source tree for each manual is organized as follows: - -File/Directory | Content -----------------------------------------------|----------------------------------------------------------------------------------------------------------- -**```pom.xml```** | Maven Project Object Model (POM) used to build the document. -**```src/```** | The source files used to define the document. -**```src/asciidoc```** | Asciidoc files for the document. -**```src/asciidoc/index.adoc```** | Main asciidoc defining the document. Includes the different chapters from the **```_chapters```** directory. -**```src/asciidoc/_chapters/```** | Source files for the different chapters in the document. -**```images/```** | Images used in the document. -**```resources/```** | Other include materials; for example, source examples that are included with the document. -**```target/```** | Build output directory. Contains the web book, the PDF file, and supporting directories. -**```target/index.pdf```** | Generated PDF version of the document. -**```target/images/```** | Copy of the **```images/```** directory. -**```target/resources/```** | Copy of the **```resources/```** directory. -**```target/site/```** | Generated web-book directory. -**```target/site/index.html```** | Generated web book. -**```target/site/css/```** | Stylesheets related to the web book. The common stylesheet is included in the index.html file. -**```target/site/images/```** | Copy of the **```images/```** directory. -**```target/site/resources/```** | Copy of the **```resources/```** directory. - -# Making Changes - -Please refer to the following web sites for guidance for information about working on asciidoc-based documentation. - -* [DCS Contributing to Documentation](https://github.com/apache/incubator-trafodion/blob/master/dcs/src/main/asciidoc/_chapters/appendix_contributing_to_documentation.adoc) -* [AsciiDoc User Guide](http://www.methods.co.nz/asciidoc/chunked/index.html) -* [AsciiDoc cheatsheet](http://powerman.name/doc/asciidoc) -* [PDF Theme](https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc) - -Once you have made the desired changes, then do the following: - -## Building an Individual Document - -1. Be sure to source env.sh, so that the TRAFODION_VER environment variable is defined. -2. Build the document using **```mvn clean site```** in the directory containing the document; for example: **```dcs```** or **```docs/odb_user```**. - * If you have not previously built the JDBC drivers, the DCS and REST documents will give spurious errors about missing that dependency. The documents can be built fine, skipping over that dependency using **```mvn -P'!jdbc' site```**. -3. Verify the content in the generated **```target```** directory. - * The **```target/index.html```** file provides the entry point for the web book. - * For those that have API documentation, the **```target/apidocs/index.html```** file contains the entry point. - * For those that have PDF, the **```target/index.pdf```** file contains the PDF version of the document. - -## Building the Entire Website, including Documents - -1. Be sure to source env.sh, so that the TRAFODION_VER environment variable is defined. -2. Build everything using **```mvn clean post-site```** in the top-level directory. - * As above, to skip over JDBC dependency, use **```mvn -P'!jdbc' post-site```**. -3. Verify the contents in the generated **```docs/target```** directory. - * All documents are in **```docs/target/docs```** directory. - -# Build Trafodion Document Tree -The external version of the Trafodion Document Tree is published to http://trafodion.incubator.apache.org/docs. Please refer to [Publish](#publish) below. - -The build version of the Trafodion Document Tree is located in **```docs/target/docs```**, which is created when you build the Trafodion web site in Maven. - -## Version Directories - -The Trafodion Document Tree consists of **Version Directories**: - -Version Directory | Content | Web Site Directory -----------------------------|---------------------------------------------------|---------------------------------------------------- -**```latest```** | Known place for the latest version of a document. | **```trafodion.incubator.apache.org/docs/<document-name>```** -**```<version>```** | Release-specific version of a document. | **```trafodion.incubator.apache.org/docs/<version>/<document-directory>```** - -* **```latest```**: Provides a well-known place for each document. This practice makes it possible to link to a document in instructional text, web sites, and -other documents. -* **```<version>```**: Provides per-release versions of documents. Previous versions are kept in the web site's git repository ensuring that previous versions of the documentation are available. - -## Document Directories -Each document is placed in its own **Document Directory**: - -Document | Document Directory Name ---------------------------|------------------------------------------ -Client Installation Guide | **```client_install```** -Command Interface Guide | **```command_interface```** -DCS Reference Guide | **```dcs_reference```** -odb User Guide | **```odb_user```** -REST Reference Guide | **```rest_reference```** -SQL Reference Manual | **```sql_reference```** - -The Document Directories are organized as follows. Files and sub-directories may or may not be present in the Document Directory depending on document. - -File/Directory | Content ------------------------------|------------------------------------------------------------------------------------------------------ -**```*.pdf```** | The PDF version of the document. For example, **```Trafodion_SQL_Reference_Guide.pdf```**. -**```index.html```** | The web book version of the document. Generated by asciidoc. -**```apidocs```** | API documentation provided as a web book. Generated by javadoc. -**```apidocs/index.html```** | Entry point for API documentation. Generated by javadoc. -**```css```** | CSS definitions used by the web-version of the document. Populated by asciidoc. -**```images```** | Images used by the web-version of the document. Populated by asciidoc. -**```resouces```** | Resource files referenced for source download etc. Populated by asciidoc. - -The Document Directories are copied under the Version Directories thereby creating the web-accessible Trafodion document tree. - -# Publish - -<div class="alert alert-dismissible alert-info"> - <button type="button" class="close" data-dismiss="alert">&close;</button> - <p style="color:black">Publication is done when a committer is ready to update the external web site. You do <strong>not</strong> publish as part of checking in changes.</p></div> - -Refer to [Website Publishing](website.html#publishing) for how the website and documents get published. - - - http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/download.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/download.md b/docs/src/site/markdown/download.md index 8f8ad27..22dc728 100644 --- a/docs/src/site/markdown/download.md +++ b/docs/src/site/markdown/download.md @@ -24,23 +24,19 @@ Trafodion is installed onto an existing Hadoop environment. Currently, one of th We're actively working on removing this restriction. # Download -The Trafodion product environment is installed using the Trafodion Installer, which operates on Trafodion binaries only. +The Trafodion end-user environment is installed using the Trafodion Installer, which operates on Trafodion binaries only. ## Binaries The Trafodion binaries are available as a tar file. -Please download from: https://dist.apache.org/repos/dist/release/incubator/trafodion/apache-trafodion-1.3.0-incubating/ +### 1.3.0 Binaries -## Source -Build your own binaries from the Trafodion source code as follows: - -1. [Setup Build Environment](setup-build-environment.html). -2. [Build Trafodion](build.html) â use **```make package```**. +* [Trafodion Installer](http://traf-builds.esgyn.com/downloads/trafodion/publish/release/1.3.0/apache-trafodion-installer-1.3.0-incubating-bin.tar.gz) +* [Trafodion Server](http://traf-builds.esgyn.com/downloads/trafodion/publish/release/1.3.0/apache-trafodion-1.3.0-incubating-bin.tar.gz) +* [Trafodion Clients](http://traf-builds.esgyn.com/downloads/trafodion/publish/release/1.3.0/apache-trafodion-clients-1.3.0-incubating-bin.tar.gz) -Git site: [email protected]:apache/incubator-trafodion - -The source tar file has been signed with pgp key A44C5A05 which is included in the download locationâs KEYS file: -https://dist.apache.org/repos/dist/release/incubator/trafodion/KEYS +## Source +Refer to the [Trafodion Contributor Guide](https://cwiki.apache.org/confluence/display/TRAFODION/Trafodion+Contributor+Guide) for information how to download and build the Trafodion source. # Install Please refer to the [Install](install.html) instructions. http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/index.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/index.md b/docs/src/site/markdown/index.md index 8f1e0bc..889f3cf 100644 --- a/docs/src/site/markdown/index.md +++ b/docs/src/site/markdown/index.md @@ -90,7 +90,7 @@ Trafodion builds on the scalability, elasticity, and flexibility of Hadoop. Traf <table> <tr> - <td width="25%" valign="top"> + <td width="33%" valign="top"> <center> <h2>Understand</h2> <img src="images/logos/understand.png" width="108" height="108"/> @@ -104,7 +104,7 @@ Trafodion builds on the scalability, elasticity, and flexibility of Hadoop. Traf <li><a href="roadmap.html">Roadmap</a></li> </ul> </td> - <td width="25%" valign="top"> + <td width="33%" valign="top"> <center> <h2>Use</h2> <img src="images/logos/use.png" width="108" height="108"/> @@ -118,21 +118,7 @@ Trafodion builds on the scalability, elasticity, and flexibility of Hadoop. Traf <li><a href="release-notes.html">Release Notes</a></li> </ul> </td> - <td width="25%" valign="top"> - <center> - <h2>Contribute</h2> - <img src="images/logos/contribute.png" width="108" height="108"/> - <h4>Help enhance Trafodion</h4> - <div class="customHr">.</div> - </center> - <ul> - <li><a href="develop.html">Develop</a></li> - <li><a href="test.html">Test</a></li> - <li><a href="document.html">Document</a></li> - <li><a href="advocate.html">Advocate</a></li> - </ul> - </td> - <td width="25%" valign="top"> + <td width="33%" valign="top"> <center> <h2>Community</h2> <img src="images/logos/community.png" width="108" height="108"/> @@ -140,7 +126,7 @@ Trafodion builds on the scalability, elasticity, and flexibility of Hadoop. Traf <div class="customHr">.</div> </center> <ul> - <li><a href="contribute.html">Join</a></li> + <li><a href="contribution-redirect.html">Contribute</a></li> <li><a href="mail-lists.html">Discuss</a></li> <li><a href="calendar.html">Calendar</a></li> <li><a href="presentations.html">Presentations</a></li> http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/install.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/install.md b/docs/src/site/markdown/install.md index e191915..7541cf8 100644 --- a/docs/src/site/markdown/install.md +++ b/docs/src/site/markdown/install.md @@ -12,9 +12,10 @@ limitations under the License. --> -This page describes how to install the Trafodion product environment. [Create Development Environment](create-dev-environment.html) describes how to create the Trafodion Development Test Environment. +This page describes how to install the Trafodion end-user environment. Refer to the [Trafodion Contributor Guide](https://cwiki.apache.org/confluence/display/TRAFODION/Trafodion+Contributor+Guide) for information how to build the Trafodion source and run the +Trafodion developer test environment. -The Trafodion product environment is installed using the Trafodion Installer, which operates on Trafodion binaries only. Refer to the [Download](download.html) page for instructions about how you download/create the Trafodion binaries. +The Trafodion end-user environment is installed using the Trafodion Installer, which operates on Trafodion binaries only. Refer to the [Download](download.html) page for instructions about how you download/create the Trafodion binaries. # Preparation The Trafodion Installer assumes that you've performed the following steps before a Trafodion install: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/manage-dev-environment.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/manage-dev-environment.md b/docs/src/site/markdown/manage-dev-environment.md deleted file mode 100644 index 2559c8d..0000000 --- a/docs/src/site/markdown/manage-dev-environment.md +++ /dev/null @@ -1,51 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how you manage the Trafodion development test environment, which is intended for people that are contributing to the Trafodion source tree. Please refer to [Download](download.html) if you want to try the Trafodion product environment. - -# Prerequisites -You must have created the [Trafodion Development Environment](create-dev-environment.html) before using the instructions on this page. - -# Hadoop Enviroment -## Pre-Existing Hadoop -If you are doing Trafodion development on a pre-existing Hadoop distribution, then do the following: - -* **Distribution**: Use the distribution management too. For example: Apache Ambari or Cloudera Manager. -* **Regular Hadoop**: Use the start/stop script for each Hadoop environment. - -## Local Hadoop -Use the following commands to manage the Hadoop environment. - -Command | Usage ------------------------------------|----------------------------------------- -**```swstartall```** | Start the complete Hadoop environment. -**```swstopall```** | Stops the complete Hadoop environment. -**```swstatus```** | Checks the status of the Hadoop environment. -**```swuninstall_local_hadoop```** | Removes the Hadoop installation. - -# Trafodion -Please refer to [Trafodion Management](management.html). - -# New Source Download -You need to do the following each time you download new source code. - - cd <Trafodion source directory> - source ./env.sh - cd $MY_SQROOT/etc - # delete ms.env, if it exists - rm ms.env - cd $MY_SQROOT/sql/scripts - sqgen - - http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/merge.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/merge.md b/docs/src/site/markdown/merge.md deleted file mode 100644 index ed91a75..0000000 --- a/docs/src/site/markdown/merge.md +++ /dev/null @@ -1,140 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how a committer merges changes into the git repository. - -Additional information about the Apache committer process can be found on the [Git at the Apache Software Foundation](https://git-wip-us.apache.org/) page. - -# Initial Set Up - -<table> - <tr> - <th width="15%">Step</th> - <th width="35%">Task</th> - <th width="50%">How-To</th> - </tr> - <tr> - <td><strong>Configure git E-Mail</strong></td> - <td>Configure <strong><code>git</code></strong> to use your Apache e-mail address.</td> - <td><pre>git config --global user.email [email protected]</pre></td> - </tr> - <tr> - <td><strong>Check <code>trafodion-contributors</code> group</strong></td> - <td>Check that your github user is a <strong>public</strong> member in the <strong><code>trafodion-contributors</code></strong> group. This allows some permissions with the Jenkins test server.</td> - <td><a href="https://github.com/orgs/trafodion-contributors/people";>https://github.com/orgs/trafodion-contributors/people</a></td> - </tr> - <tr> - <td><strong>Set Up Work Space</strong></td> - <td>Set up your work space so that you can merge pull requests.</td> - <td> - <ul> - <li>In VNC/Gnome environment, either add to <strong><code>.bashrc</code></strong> or type at your current shell: <pre>unset SSH_ASKPASS</pre></li> - <li>Pushing code to the Apache repository requires password authentication.</li> - <li>Ensure that your work space is cloned from github: <pre>git clone https://github.com/apache/incubator-trafodion</pre></li> - <li>Ensure that you have a remote pointing to the Apache repo. (Setting only the push URL with username does not seem to work.) <pre>git remote add apache https://[email protected]/repos/asf/incubator-trafodion.git</pre></li> - </ul> - </td> - </tr> -</table> - -# Automated Testing -You can interact with Jenkins testing via pull request (PR) comments. All of these commands should start with "jenkins," to not confuse other users. You can add more to the end of the message if you want. Jenkins just pattern matches the string, and will ignore trailing comments. - -* If an unknown user submits a PR, then Jenkins automation will post a message to github asking if it is okay to test. - * Review the pull request. If the code is not malicious and is okay to test, post a comment <pre>jenkins, ok</pre> - -* If the author is a trusted contributor, you can add them to a white-list of known users. - * Post a comment <pre>jenkins, add user</pre> - -* Consider inviting them to the **```trafodion-contributors```** github group as well. - * New commits to the PR will trigger a new build. You can also trigger a retest without a new commit. - * Post a comment <pre>jenkins, retest</pre> - -# Validate Review Criteria -The project committee (PPMC) has agreed that the following review criteria are used for contributions: - -* Code Review(s) -* Time available for comments -* Testing - * **Be sure that you wait for all pending tests!** - * New commits, even those that are just merging with latest master branch, trigger new test run. -* Legal -* Other - -# Merge Pull Request -Use the following procedure to merge a pull request. - -<table> - <tr> - <th width="15%">Step</th> - <th width="35%">Task</th> - <th width="50%">Commands</th> - </tr> - <tr> - <td><strong>Check Status</strong></td> - <td> - <p>Check the pull request status on github, at the bottom of the pull request page. It will tell you if there are any merge conflicts with master branch.</p> - <p><strong>NOTE</strong></p> - <p>If there are conflicts, either ask the contributor to merge up, or be prepared to resolve the conflicts yourself.</p> - </td> - <td></td> - </tr> - <tr> - <td><strong>Create Local Merge Branch</strong></td> - <td>Create a local merge branch, based on the latest, greatest.</td> - <td><pre># You will be prompted for your Apache password -git fetch apache -git checkout -b mrg_12345 apache/master</pre></td> - </tr> - <tr> - <td><strong>Fetch Pull Request Branch</strong></td> - <td>Fetch pull request branch to default destination <strong><code>FETCH_HEAD</code></strong></td> - <td><pre>git fetch origin +refs/pull/12345/head</pre></td> - </tr> - <tr> - <td><strong>Merge Locally</strong></td> - <td>Merge locally, giving message that includes JIRA ID.</td> - <td> - <p><pre>git merge --no-ff -m "Merge [TRAFODION-XYZ] PR-12345 Whizbang feature" \ -FETCH_HEAD</pre></p> - <p><strong>NOTES</strong></p> - <ul> - <li>Sometimes you might want to squash their branch into a single commit. If so, add the <strong><code>--squash</code></strong> option.</li> - <li>If you forget the <strong><code>-m</code></strong> option, you end up with a less than helpful default comment. - <ul> - <li><strong>Before you push the commit</strong>, you can fix the comment by:<pre>git commit --amend</pre></li> - </ul> - </li> - </ul> - </td> - </tr> - <tr> - <td><strong>Additional Checks</strong></td> - <td>Additional checks of what you are preparing to push.</td> - <td> - <pre>git log apache/master..HEAD -git diff apache/master HEAD</pre></td> - </tr> - <tr> - <td><strong>Push Changes</strong></td> - <td>Push changes to the Apache repository, specifying the source and the destination branch.</td> - <td><pre># You will be prompted for your Apache password -git push apache HEAD:master</pre></td> - </tr> -</table> - -# Completion - -1. Close Jira, if appropriate, or ask the contributor to do so. -2. If ASF automation does not close the pull request, ask the contributor to do so. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/release.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/release.md b/docs/src/site/markdown/release.md deleted file mode 100644 index 16e5391..0000000 --- a/docs/src/site/markdown/release.md +++ /dev/null @@ -1,225 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how to create a Trafodion release. You have to be a Trafodion committer to use these instructions. - -# Prerequisites - -## Create PGP Key -If you haven't done so already, then you need to create a PGP key so that you can sign the release. Please refer to: http://www.apache.org/dev/openpgp.html#generate-key. - -Please remember to store your private key in a secure place. - -**Example** - - gpg --gen-key (verify that sha1 is avoided (last on list â see above web site) - gpg -k (shows public key) - gpg -K (shows private key) - -### Upload Public Key -Upload your public key to a public key server. We recommend using https://pgp.mit.edu/. - -**Example** - - gpg --send-keys <keyID> --keyserver pgp.mit.edu - -### Create Revocation Certificate -Create a revocation certification using the instructions at: http://www.apache.org/dev/openpgp.html#revocation-certs. - -Please remember to store it in a secure place separate from your PGP keys. - -**Example** - - gpg --output revoke-<keyD>.asc --armor --gen-revoke <keyID> - -# Add PGP to KEYS File -Do the following: - - svn co https://dist.apache.org/repos/dist/release/incubator/trafodion traf_release - cd traf_release - gpg --list-sigs <keyID> >> KEYS - gpg -armor âexport <keyID> - svn commit âm âadded new public key to KEYS fileâ - -# Prepare Artifacts -## Prepare New Release - -1. Send a message out to the community indicating that a new release is being planned. In this message, indicate what is planned for the release and when the release is scheduled. -2. Give contributors enough time to assimilate this information so they can make plans to deliver their changes. Recommend giving the community several weeks notice. -3. Review open issues and planned features; determine what JIRA's should be included in the release. - -## Verify Release Requirements -You need to ensure that: - -* A DISCLAIMER file exists in the top level directory containing correct information. Please refer to: http://incubator.apache.org/guides/branding.html#disclaimers. -* NOTICE and LICENSE files exist in the top level directory which includes all third party licenses used in the product. Please refer to: http://www.apache.org/dev/licensing-howto.html. -* A README file exists and is up to date in the top level directory describing the release. -* The source release contains source code only, no binaries. -* The provenance of all source files is clear. -* All source files have Apache license headers, where possible. Where not possible, then the exceptions are written up in the RAT_README file located in the top level directory. -* RAT report is clean. -* Copyright dates are current. -* Build instructions are provided and can be run successfully. -* Test instructions are provided and can be run successfully. - -## Create Release Branch -Prior to releasing, send a message to the community indicating that a new release is imminent and that a new branch will be created to build the artifacts. - -After the new release branch is created, send another message to the community indicating that the branch is available and the deliveries will be monitored. Allow deliveries on the main branch to continue. - -Verify that all required changes have been delivered. - -## Create Artifacts -Trafodion uses git as its repository. When a new version is created, mark the repository with the tag to make sure it source tar can be recreated. - -### Create Tag - -**Example: Release x.x.x and release candidate 1 (rc1)** - - git checkout -b tagx.x.x <release branch name> - git tag -a x.x.xrc1 - git show x.x.xrc1 - git push apache x.x.xrc1 - git tag - -Once completed, a new source tar file exist in the distribution directory. - -### Create Artifact Checksums and Signatures -**Assumption**: You've already created the signing key and registered it at the https://pgp.mit.edu/ repository. - - gpg --armor --output apache-trafodion-x.x.x-incubating-src.tar.gz.asc --detach-sig apache-trafodion-x.x.x-incubating-src.tar.gz - gpg --verify apache-trafodion-x.x.x-incubating-src.tar.gz.asc - md5sum apache-trafodion-x.x.x-incubating-src.tar.gz > apache-trafodion-x.x.x-incubating-src.tar.gz.md5 - sha1sum apache-trafodion-x.x.x-incubating-src.tar.gz > apache-trafodion-x.x.x-incubating-src.tar.gz.sha - -# Test Artifacts - -## Build and Test Source tar File -Build and test the source tar file using the [Build Trafodion](build.html) instructions. You should perform this test on the following environments: - -* Test build on a fresh VM. -* Test build using the tagged version from git - -## Compare Tagged Version with Source tar File -Compare the code from the source tar file with the tagged version to make sure they match. The follow example assumes that the branch artifacts contains the release candidates. - - mkdir traf_test - cd traf_test - cp <git dir>/incubator-trafodion/distribution/* . - tar zxf apache-trafodion-x.x.x-incubating-src.tar.gz - -Compare the two versions; for example, by using BCompare and the "Folder Compare Report" feature: - - old: traf_test/incubator-trafodion - new: <git dir>/incubator-trafodion - -**Note:** The git version will have some additional git folders and the distribution directory. - -## Verify Apache Requirements -Verify checksums and signatures using the [Verify Signature](#Verify_Signatures) instructions below. - -Ensure that the high-level directory contains valid version of: - -* **```DISCLAIMER.txt```** -* **```LICENSE.txt```** -* **```NOTICE.txt```** -* **```RAT_README.txt```** -* **```README.txt```** - -# Stage Artifacts -Once all the artifacts have been created and tested, then it's time to stage them. Upload the artifacts to the https://dist.apache.org/repos/dist/dev/incubator/trafodion directory. - -1. Make sure **```svn```** exists. (It can be downloaded using **```yum```**.) - * **```which svn```** - * **```svn --version```** (version 1.6.11 works) -2. Create a directory to store the **```svn```** repositoy -3. Checkout source code. This creates a directory called incubator. - * **```svn co https://dist.apache.org/repos/dist/dev/incubator```** -4. **```cd trafodion```** -5. Create a new directory for the release: **```mkdir apache-trafodion-x.x.x-incubating```** -6. **```cd <apache-trafodion-x.x.x-incubating>```** -7. Copy the four files to the incubating directory. -8. Ensure that you do an **```svn add```** for the new directory and all four files -9. Ask for a review of the changes -10. Commit your changes - * **```svn status```** - * **```svn commit âm "messageâ¦"```** - * Go to https://dist.apache.org/repos/dist/dev/incubator to see if your changes were committed - -# Verification -All artifacts have been uploaded to the staging area. - -## Verify Signatures -Download all the artifacts from the staging area including: - - apache-trafodion-x.x.x-incubating-src.tar.gz - apache-trafodion-x.x.x-incubating-src.tar.gz.asc - apache-trafodion-x.x.x-incubating-src.tar.gz.md5 - apache-trafodion-x.x.x-incubating-src.tar.gz.sha - -Check signatures and checksums. - -**```apache-trafodion-x.x.x-incubating-src.tar.gz.asc```** - - # View public key - gpg apache-trafodion-x.x.x-incubating-src.tar.gz.asc - - # Expect - gpg: Signature made Tue 03 Nov 2015 12:59:10 AM UTC using RSA key ID A44C5A05 - gpg: Can't check signature: No public key - - # Extract public key from key ID returned above - gpg --keyserver pgpkeys.mit.edu --recv-key A44C5A05 - - # Expect: - gpg: requesting key A44C5A05 from hkp server pgpkeys.mit.edu - gpg: /home/centos/.gnupg/trustdb.gpg: trustdb created - gpg: key A44C5A05: public key "Jane Doe (CODE SIGNING KEY) <[email protected]>" imported - - # Verify signature - gpg --verify apache-trafodion-x.x.x-incubating-src.tar.gz.asc - # Expect: - gpg: Signature made <date> using RSA key ID A44C5A05 - gpg: Good signature from "Roberta Marton (CODE SIGNING KEY) <[email protected]>" - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - - **```apache-trafodion-x.x.x-incugating-src.tar.gz.md5```** - - md5sum -c apache-trafodion-x.x.x-incubating-src.tar.gz.md5 - - # Expect: - apache-trafodion-x.x.x-incubating-src.tar.gz: OK - -**```apache-trafodion-x.x.x-incubating-x.x.x-incubating-src.tar.gz.sha```** - - sha1sum -c apache-trafodion-x.x.x-incubating-src.tar.gz.sha - - # Expect: - apache-trafodion-x.x.x-incubating-src.tar.gz: OK - -## Verify Apache Requirements -Ensure that the high-level directory contains valid version of: - -* **```DISCLAIMER.txt```** -* **```LICENSE.txt```** -* **```NOTICE.txt```** -* **```RAT_README.txt```** -* **```README.txt```** - -Next, run **```rat```** to make sure all files have Apache copyrights. - -# Complete Release - -To be completed. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/setup-build-environment.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/setup-build-environment.md b/docs/src/site/markdown/setup-build-environment.md deleted file mode 100644 index 6de4cd5..0000000 --- a/docs/src/site/markdown/setup-build-environment.md +++ /dev/null @@ -1,160 +0,0 @@ -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the - License. ---> -This page describes how you set up the Trafodion build environment. - -# Supported Platforms -Red Hat or Centos 6.x (6.4 or later) versions are supported as development and production platforms. - -# Install Required Packages -You need to install the following packages before you can build Trafodion. - - sudo yum install epel-release - - sudo yum install alsa-lib-devel ant ant-nodeps boost-devel cmake \ - device-mapper-multipath dhcp flex gcc-c++ gd git glibc-devel \ - glibc-devel.i686 graphviz-perl gzip java-1.7.0-openjdk-devel \ - libX11-devel libXau-devel libaio-devel \ - libcurl-devel libibcm.i686 libibumad-devel libibumad-devel.i686 \ - libiodbc libiodbc-devel librdmacm-devel librdmacm-devel.i686 \ - libxml2-devel log4cxx log4cxx-devel lua-devel lzo-minilzo \ - net-snmp-devel net-snmp-perl openldap-clients openldap-devel \ - openldap-devel.i686 openmotif openssl-devel openssl-devel.i686 \ - openssl-static perl-Config-IniFiles perl-Config-Tiny \ - perl-DBD-SQLite perl-Expect perl-IO-Tty perl-Math-Calc-Units \ - perl-Params-Validate perl-Parse-RecDescent perl-TermReadKey \ - perl-Time-HiRes protobuf-compiler protobuf-devel python-qpid \ - python-qpid-qmf qpid-cpp-client \ - qpid-cpp-client-ssl qpid-cpp-server qpid-cpp-server-ssl \ - qpid-qmf qpid-tools readline-devel saslwrapper sqlite-devel \ - unixODBC unixODBC-devel uuid-perl wget xerces-c-devel xinetd - -# Verify Java Version -The Java version must be 1.7.x. Check as following: - - $ java -version - java version "1.7.0_85" - OpenJDK Runtime Environment (rhel-2.6.1.3.el6_6-x86_64 u85-b01) - OpenJDK 64-Bit Server VM (build 24.85-b03, mixed mode) - -Ensure that the Java environment exists and points to your JDK installation. By default Java is located in **```/usr/lib/java-\<version\>```**. - - $ echo $JAVA_HOME - $ export JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk.x86_64 - -# Download and Install Source -The Trafodion source code contains tools that help you set up the build environment. -## Git -Please refer to [Making Changes](develop.html#making_changes) on the [Develop](develop.html) page. - -## tar file -The source code for Apache Trafodion can be downloaded from [Apache Trafodion Incubator Release](https://dist.apache.org/repos/dist/release/incubator) as a tar file. - -* Download the source tar file to your **```<trafodion download directory>```**. -* Check the tar file validity by checking signatures, please refer to [Verify Signatures](release.html#Verify_Signatures). The Trafodion releases have been signed using The GNU Privacy Guard. - -**Unpack the tar file** - - cd <trafodion download directory> - tar -xzf <tar file> - -# Install Build Tools -Trafodion requires that several tools are installed in order to build. These tools are: - -Tool | Description ----------------------------------------|----------------------------------------------------------------- -**Bison** | General-purpose parser generator. -**ICU** | Set of C/C++ and Java libraries providing Unicode and Globalization support for software applications. -**LLVM** | Collection of modular and reusable compiler and tool-chain technologies. -**Maven** | Build tool that is only installed if compatible version does not exist. -**MPICH** | An implementation of the Message Passing Interface (MPI) standard. For use in Trafodion, MPICH must be built to force sockets to be used in both internode and intranode message passing. -**Thrift** | Communications and data serialization tool. -**Udis86** | Minimalistic disassembler library (libudis86) for the x86 class of instruction set architectures. -**Zookeeper** | Coordination service for distributed applications. It exposes common services such as naming, configuration management, synchronization, and group services. - -You can perform the required installation using the Trafodion **```traf_tools_setup.sh```** script or by installing each tool manually. - -## ```traf_tools_setup.sh``` -**```traf_tools_setup.sh```** is a script that uses **```wget```** to download the appropriate tar file, build, and install the required tool into a directory of your choice for each tool required tools. - -The advantage of this method is that all the correct tools are downloaded and built in a single directory. Before building, a single environment variable needs to be set: **```TOOLSDIR```**. - -<div class="alert alert-dismissible alert-info"> - <button type="button" class="close" data-dismiss="alert">&close;</button> - <p style="color:black"><strong>Note</strong></p> - <p style="color:black">You may want to modify <strong><code>traf_tools_setup.sh</code></strong> for your specific environment. Example: if you already have Zoopkeeper installed, you may not want to re-install it.</p> - <p style="color:black">You may need root or sudo access to installs the tools in desired locations.</p> - <p style="color:black">In the sections below, <strong><code>incubator-trafodion</code></strong> represents the root directory where you installed the Trafodion source.</p> -</div> - -**Usage** - - cd <Trafodion source directory>/install - ./traf_tools_setup.sh -h - Usage: ./traf_tools_setup.sh -d <downloaddir> -i <installdir> - -d <downloaddir> - location of download directory - -i <installdir> - location of install directory - -h - help - example: traf_tools_setup.sh -d /home/userx/download -i /home/userx/tools - -Run **```traf_tools_setup.sh```** to install all dependent tools. - -**Example** - - $ mkdir ~/download - $ ./traf_tools_setup.sh -d ~/download -i ~/tools - INFO: Starting tools build on Fri Nov 6 21:33:53 PST 2015 - Tools install directory /home/centos/tools does not exist, do you want to to create it? y/n : y - INFO: Created directory /home/centos/tools - INFO: Tar download location: /home/centos/download - INFO: Tool install directory location: /home/centos/tools - INFO: LogFile location: /home/centos/incubator-trafodion/install/traf_tools_setup.log - *********************************************************** - INFO: Installing MPI on Fri Nov 6 21:34:00 PST 2015 - INFO: downloaded tar file: mpich-3.0.4.tar.gz - . - . - . - INFO: downloaded tar file: apache-maven-3.3.3-bin.tar.gz - INFO: Maven installation complete - *********************************************************** - INFO: Completed tools build on Fri Nov 6 22:23:22 PST 2015 - INFO: List of tools directory: - apache-maven-3.3.3 - bison_3_linux - dest-llvm-3.2 - dest-mpich-3.0.4 - icu4.4 - thrift-0.9.0 - udis86-1.7.2 - zookeeper-3.4.5 - -Export **```TOOLSDIR```** in **```.bashrc```** or **```.profile```**. - - export TOOLSDIR=~/tools - -## Manual Installation -Please refer to [Build Tools Manual Installation](build-tools-manual.html). - -# Verify Build Environment -## Verify Maven -Check that Maven is installed. - - mvn --version - -If Maven is not found, then you should add Maven to your **```PATH```** environmental variable in **```.bashrc```** or **```.profile```**. - - PATH=$PATH:<tool installation directory>/apache-maven-3.3.3/bin - -At this point, your build environment has been set up. You should now be able to [Build Trafodion](build.html). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/3063990d/docs/src/site/markdown/team-redirect.md ---------------------------------------------------------------------- diff --git a/docs/src/site/markdown/team-redirect.md b/docs/src/site/markdown/team-redirect.md new file mode 100644 index 0000000..4fe0aa2 --- /dev/null +++ b/docs/src/site/markdown/team-redirect.md @@ -0,0 +1,18 @@ +<!-- + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the + License. +--> +Redirecting to the Trafodion wiki... +<p><meta http-equiv="refresh" content="0; url=https://cwiki.apache.org/confluence/display/TRAFODION/Contributors";></meta></p> + +<!-- This page is here to ensure that we track page requests in Google Analytics. --> \ No newline at end of file
