You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@age.apache.org by ey...@apache.org on 2021/02/09 20:55:53 UTC
[incubator-age] 09/18: adding dev docs
This is an automated email from the ASF dual-hosted git repository.
eya pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-age.git
commit 35071c44f6f2ecc560c9ffd98ad3ad8b1273e348
Author: Nick Sorrell <ni...@cint.io>
AuthorDate: Wed Dec 2 16:29:06 2020 -0500
adding dev docs
---
assets/styles/index.css | 15 +-
examples.c | 99 +++++++++++++
index.html | 360 +++++++++++++++++++++++++++++++++++++++++++-----
3 files changed, 436 insertions(+), 38 deletions(-)
diff --git a/assets/styles/index.css b/assets/styles/index.css
index 25f781a..97aac4c 100644
--- a/assets/styles/index.css
+++ b/assets/styles/index.css
@@ -52,6 +52,7 @@
background-color: rgb(240, 239, 239);
padding-left: 1rem;
padding-right: 1rem;
+ display: block;
}
@media only screen and (max-width: 800px) {
.sidebar {
@@ -82,6 +83,7 @@
grid-column: 2 / 3;
grid-row: 2;
padding-right: 2rem;
+ overflow: auto;
}
@media only screen and (max-width: 800px) {
.main {
@@ -121,7 +123,12 @@
* GENERAL
*/
- .center {
+.heading {
+ font-size: 1.3rem;
+ padding-left: .5rem;
+}
+
+.center {
text-align: center;
margin: auto;
}
@@ -161,6 +168,12 @@
padding-right: .4rem;
}
+.codebox {
+ border: 5px solid black;
+ white-space: pre;
+ overflow: auto;
+}
+
.external-link::after {
color: blue;
content: "➚";
diff --git a/examples.c b/examples.c
new file mode 100644
index 0000000..9977df7
--- /dev/null
+++ b/examples.c
@@ -0,0 +1,99 @@
+switch (suffix) {
+ case 'G':
+ case 'g':
+ mem <<= 30;
+ break;
+ case 'M':
+ case 'm':
+ mem <<= 20;
+ break;
+ case 'K':
+ case 'k':
+ mem <== 10;
+ // fall through
+ default:
+ break;
+}
+
+//
+int function(int x)
+{
+ body of function
+}
+
+struct s
+{
+ int a;
+ int b;
+}
+
+if (x is true)
+{
+ we do a
+}
+else if (y is true)
+{
+ we do b
+}
+else
+{
+ we do c
+ we do d
+}
+
+//
+if (x is true)
+ we do a
+if (y is true)
+ we do b
+else
+ we do c
+
+//
+do
+{
+ body of do-loop
+} while (condition);
+
+//
+
+/*
+ * This function
+ * does x
+ */
+void f(void)
+{
+ // This is to check...
+ if (y is true)
+ we do b
+
+ /*
+ * We need to do this here
+ * because of ...
+ */
+ for (;;)
+}
+
+//
+//do this
+#define Anum_ag_graph_name 1
+#define Anum_ag_graph_namespace 2
+
+//not this
+#define Anum_ag_graph_name 1
+#define Anum_ag_graph_namespace 2
+
+//
+// do this
+#define f() \
+ do \
+ { \
+ run(); \
+ } while (0)
+
+// not this
+#define f() \
+ do \
+ { \
+ run(); \
+ } while (0)
diff --git a/index.html b/index.html
index 047faa7..ed5baaf 100644
--- a/index.html
+++ b/index.html
@@ -47,7 +47,7 @@
<p class="sidebar--section">
<span class="emph">CONTRIBUTION</span> <br />
<span id="sidebar-contribute" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">How to Contribute</a></span> <br />
- Coding Guideline <br />
+ <span id="sidebar-devguidelines" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Developer Guidelines</a></span> <br />
</p>
<p class="sidebar--section">
@@ -74,7 +74,7 @@
*
-->
<div class="main-item main--selected" id="main-overview">
- <div class="title">Apache AGE (Incubating)</div>
+ <div class="heading"><h1>Apache AGE (Incubating)</h1></div>
<div class="main-body">
<p class="main-content">
Apache AGE a PostgreSQL extension that provides graph database functionality. AGE is an acronym for AgensGraph Extension, and is inspired by Bitnine's fork of
@@ -82,7 +82,7 @@
so that users can use standard ANSI SQL along with openCypher, the Graph query language.
</p>
- <div class="subtitle">Features</div>
+ <div class="heading"><h2>Features</h2></div>
<ul>
<li> PostgreSQL version AGE supports</li>
<li> openCypher ... version AGE supports </li>
@@ -91,7 +91,7 @@
<li> Aggregation ... brief explanation </li>
</ul>
- <div class="subtitle">News & Updates</div>
+ <div class="heading"><h2>News & Updates</h2></div>
<ul>
<li>2020-12-1
<ul>
@@ -104,11 +104,11 @@
</div>
</div>
<div class="main-item" id="main-license">
- <div class="title">License</div>
+ <div class="heading"><h1>License</h1></div>
<div class="main-body">Apache AGE is licensed under <a target="_blank" href="http://www.apache.org/licenses/LICENSE-2.0.html">Apache License, version 2.0</a></div>
</div>
<div class="main-item" id="main-roadmap">
- <div class="title">Roadmap</div>
+ <div class="heading"><h1>Roadmap</h1></div>
<div class="main-body">here is the roadmap</div>
</div>
@@ -118,8 +118,8 @@
*
-->
<div class="main-item" id="main-installing">
- <div class="title">Installing AGE</div>
- <div class="subtitle">Using Docker</div>
+ <div class="heading"><h1>Installing AGE</h1></div>
+ <div class="heading"><h2>Using Docker</h2></div>
<div class="main-body">
Docker images are available on Docker Hub and are based on the official PostgreSQL 11 Debian and Alpine images. <br />
<ul>
@@ -127,7 +127,7 @@
<li><a class="external-link" target="_blank" href="https://hub.docker.com/r/sorrell/agensgraph-extension-alpine">AGE Alpine Docker Image</a></li>
</ul>
</div>
- <div class="subtitle">Installing from source</div>
+ <div class="heading"><h2>Installing from source</h2></div>
<div class="main-body">
Building AGE from source depends on the following Linux libraries (Ubuntu package names shown below):
@@ -155,9 +155,9 @@ SET
</div>
</div>
<div class="main-item" id="main-gettingstarted">
- <div class="title">Getting Started</div>
+ <div class="heading"><h1>Getting Started</h1></div>
<div class="main-body">
- <div class="subtitle">Loading AGE</div>
+ <div class="heading"><h2>Loading AGE</h2></div>
Connect to your containerized Postgres instance and then run the following commands:
<div class="code">
@@ -166,7 +166,7 @@ LOAD 'age';
SET search_path = ag_catalog, "$user", public;
</div>
- <div class="subtitle">Using AGE</div>
+ <div class="heading"><h2>Using AGE</h2></div>
First you will need to create a graph:
<div class="code">
@@ -302,22 +302,16 @@ $$) as (a agtype);
*
-->
<div class="main-item" id="main-contribute">
- <div class="title">
- How to contribute
- </div>
+ <div class="heading"><h1>How to contribute</h1></div>
<div class="main-body">
There are multiple ways you can contribute to the project.And help is always welcome! All details can be
found on the contributing page. Keep reading for a quick overview!
- <div class="subtitle">
- Becoming a Commiter
- </div>
+ <div class="heading"><h2>Becoming a Commiter</h2></div>
If you are interested in the project and looking for ways to help, consult the list of tasks in JIRA, or ask the mailing list.
- <div class="subtitle">
- Contributing by Helping Other Users
- </div>
+ <div class="heading"><h2>Contributing by Helping Other Users</h2></div>
A great way to contribute to AGE is to help answer user questions on the TODO_LINK:mailing list or on TODO_LINK:StackOverflow.
There are always many new AGE users; taking a few minutes to help answer a question is a very valuable community service.
<br>
@@ -328,27 +322,21 @@ $$) as (a agtype);
as well as forums like StackOverflow.
- <div class="subtitle">
- Contributing by Reviewing Changes
- </div>
+ <div class="heading"><h2>Contributing by Reviewing Changes</h2></div>
Changes to AGE source code are proposed, reviewed, and committed via Github pull requests (described in Instruction Link).
Anyone can view and comment on active changes here. Reviewing others' changes is a good way to learn how the change process works
and gain exposure to activity in various parts of the code. You can help by reviewing the changes and asking questions
or pointing out issues as simple as typos or small issues of style.
- <div class="subtitle">
- Contributing Documentation Changes
- </div>
+ <div class="heading"><h2>Contributing Documentation Changes</h2></div>
To propose a change to release documentation (that is, docs that appear under TODO_LINK:https://AGE.apache.org/instruction/),
edit the Markdown source files in AGE's <span class="inline-code">docs/</span> directory on GitHub, whose README file shows how to
build the documentation locally to test your changes. The process to propose a doc change is otherwise the same as the
process for proposing code changes below.
- <div class="subtitle">
- Contributing Bug Reports
- </div>
+ <div class="heading"><h2>Contributing Bug Reports</h2></div>
Ideally, bug reports are accompanied by a proposed code change to fix the bug. This isn't always possible, as those who discover a
bug may not have the experience to fix it. A bug may be reported by creating a JIRA issue but without creating a pull request.
<br>
@@ -368,9 +356,7 @@ $$) as (a agtype);
to prove the problem is indeed fixed.
- <div class="subtitle">
- Contributing to JIRA Maintenance
- </div>
+ <div class="heading"><h2>Contributing to JIRA Maintenance</h2></div>
Most contributors can directly resolve JIRA issues. Use judgment in determining whether you are confident the issue should be
resolved (although changes can be easily undone).
<br>
@@ -380,7 +366,7 @@ $$) as (a agtype);
Resolve as Fixed if there's a release or code commit that resolved the issue.
<ul>
<li>
- Set Fix Version(s), if and only if the resolution is Fixeds
+ Set Fix Version(s), if and only if the resolution is Fixed
</li>
<li>
Set Assignee to the person who contributed the most to its resolution, usually the person who opened the PR that resolved the issue.
@@ -408,7 +394,7 @@ $$) as (a agtype);
If the issue doesn't make sense or is not actionable resolve as Invalid.
</li>
<li>
- If it's a coherent issue, but there is a clear indication that there is not support or interest in acting on it, then resolve as Won't Fix.
+ If it's a coherent issue, but there is a clear indication that there is no support or interest in acting on it, then resolve as Won't Fix.
</li>
</ul>
<br>
@@ -441,13 +427,313 @@ $$) as (a agtype);
</div>
</div>
+ <div class="main-item" id="main-devguidelines">
+ <div class="heading"><h1>Developer Guidelines</h1></div>
+ <div class="main-body">
+ <div class="emph">Table of Contents</div>
+ <ul>
+ <li><a href="#codereview">Code Review Process</a></li>
+ <li><a href="#merge">How to Merge a Pull Request</a></li>
+ <li><a href="#style">Coding Style Guide</a></li>
+ <li><a href="#createdocs">Creating Documentation</a></li>
+ </ul>
+ <a id="codereview"></a>
+ <div class="heading"><h2>Code Review Process</h2></div>
+ <ul>
+ <li>Make a commit (or multiple commits) on your local branch.</li>
+ <li> Create .patch file(s) of the commit(s).
+ <ul><li>Use <span class="inline-code">git format-patch</span> command. </li></ul></li>
+ <li> Send the .patch file(s) to the reviewer.
+ <ul>
+ <li>The title of the email must be "[Review] [JIRA Ticket Name Here] summary-of-the-issue"
+ <br>(e.g. [Review] [JIRA Ticket Name] Support changing graph name)
+ <ul><li>If the commit is not for any issues on Jira, omit " [JIRA Ticket Name Here]". OR make a Jira ticket</li></ul>
+ </li>
+ <li> The email body will look like this:
+ <div class="codebox">
+Commit bef50e5d86d45707806f5733695a229f3e295b1a
+[one blank line]
+Description
+ </div>
+
+ <ul>
+ <li>
+ The first line is the hash code of the base commit, NOT the commit you've created.
+ <ul>
+ <li>This will help reviewers to quickly apply the .patch files.</li>
+ </ul>
+ </li>
+ <li>Put proper information to help the reviewer.</li>
+ </ul>
+ </li>
+ <li>
+ Attach .patch files.
+ <ul>
+ <li>Do NOT rename files. They are named with numbers in order.</li>
+ <li>Do NOT compress them unless the total file size is over 5MB.</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li> Reply to the last email in the same thread to send a review of it.
+ <ul><li>You can attach some .diff files. </li></ul>
+ </li>
+ <li> Reply to the last email in the same thread to send updated patch(es) and opinions.
+ <ul><li>If you rebase commits, state the hash code of the new base commit. </li></ul>
+ </li>
+ <li>Repeat 4 and 5.</li>
+ </ul>
+ <!-- END CODE REVIEW -->
+ <hr>
+ <!-- BEGIN MERGE PR -->
+ <a id="merge"></a>
+ <div class="heading"><h2>How to Merge a Pull Request</h2></div>
+ <p class="emph">Single Commit for a Single Task</p>
+
+ In this case, the commit will be merged into the master branch with the following process.
+ <br>
+ <ol>
+ <li>
+ Change the current working branch to the local master branch by running the following command.
+ <div class="code">$ git checkout master </div>
+ </li>
+
+ <li> Make the local master branch up-to-date by running the following command (or any other commands that result the same.)
+ <div class="code">$ git pull </div></li>
+
+ <li> Change the current working branch to the local task branch that the commit resides in by running the following command.
+ <div class="code">$ git checkout</div> </li>
+
+ <li> Rebase the local task branch by running the following command.
+ <div class="code">$ git rebase master</div> </li>
+
+ <li>Resolve any conflicts that occur during rebase.</li>
+
+ <li> Change the current working branch to the local master branch by running the following command.
+ <div class="code">$ git checkout master</div> </li>
+
+ <li> Merge the local task branch into the local master branch by running the following command.
+ <div class="code">$ git merge </div> </li>
+ </ol>
+ <p class="emph">Multiple Commits for a Single Task</p>
+
+ Keeping Commit History <br>
+ Sometimes, having logically separated multiple commits for a single task helps developers to grasp the logical process of the work that had been done for the task. If the commits are merged with fast-forward strategy, the commits will not be grouped together. Therefore, to group the commits, create an explicit merge commit.
+ <br>
+ In this case, the commits will be merged into the master branch with the same process above except the last step(step 7).
+ <br>
+ For the last step, the local task branch will be merged into the local master branch with an explicit merge commit by running the following command. If you omit --no-ff option, the command will do fast-forward merge instead.
+
+ <div class="code">$ git merge --no-ff</div>
+
+ The above process will result, for example, the following commit history. (This is captured from bitnine/agensgraph-ext.) There is an explicit merge commit, 69f3b32. Each explicit merge commit groups related commits.
+ <div class="code codebox">
+* 9779a0b Implement property and element access operators
+* 69f3b32 Implement + (concatenating strings) operator
+|\
+| * ab50b5c Support Floating Point Precision in String Operators
+| * cceebcd Implement String Operators
+|/
+* 6c36b80 Fix failed assertion when agtype_build_map() takes agtype as key
+* 304bc68 Refactor bool_to_agtype() </div>
+ Note: There is no commit between an explicit merge commit and the parent commit, which is on the master branch, of the explicit merge commit. This is done by doing rebase before merge.
+
+ <!-- END MERGE PR -->
+ <hr>
+ <!-- BEGIN STYLE GUIDE -->
+ <a id="style"></a>
+ <div class="heading"><h2>Code Style Guide</h2></div>
+ For a full list of coding style guidelines, please refer to the style setup in the <a href="https://github.com/bitnine-oss/agensgraph-ext/blob/master/clang-format.5">clang-format.5</a> in the AGE git repository.
+
+ <div class="heading"><h3>Indentation</h3></div>
+ Use 4 spaces per indentation level. (no tab character)
+ <ul><li>You can see the same indentation in all environments.</li></ul>
+ <br>
+ For switch statement, see below.
+ <div class="code codebox">
+switch (suffix) {
+ case 'G':
+ case 'g':
+ mem <<= 30;
+ break;
+ case 'M':
+ case 'm':
+ mem <<= 20;
+ break;
+ case 'K':
+ case 'k':
+ mem <== 10;
+ // fall through
+ default:
+ break;
+}
+ </div>
+ <div class="heading"><h3>Breaking long lines and strings</h3></div>
+ The line length limit is 79 columns, except for strings longer than 79 characters.
+
+ <div class="heading"><h3>Placing Braces and Spaces</h3></div>
+ All braces are on their own line solely. See below.
+
+ <div class="code codebox">
+int function(int x)
+{
+ body of function
+}
+
+struct s
+{
+ int a;
+ int b;
+}
+
+if (x is true)
+{
+ we do a
+}
+else if (y is true)
+{
+ we do b
+}
+else
+{
+ we do c
+ we do d
+}
+ </div>
+ If all the bodies of if/else statement contain a single line, omit braces. See below.
+
+ <div class="code codebox">
+if (x is true)
+ we do a
+
+if (y is true)
+ we do b
+else
+ we do c
+ </div>
+ One exception is do statement. See the following example.
+
+ <div class="code codebox">
+do
+{
+ body of do-loop
+} while (condition);
+ </div>
+ <div class="heading"><h3>Naming</h3></div>
+ Use the underscore name convention for all variables, functions, structs, enums and define macros.
+
+ <div class="heading"><h3>Typedefs</h3></div>
+ Use typedef only for struct and enum. It must not be used for pointer types.
+
+ <div class="heading"><h3>Commenting</h3></div>
+ For multi-line comments, use C style multi-line comments.
+ <br>
+ For single-line comments, use C++ style single-line comments.
+ <br>
+ See below.
+
+ <div class="code codebox">
+/*
+ * This function
+ * does x
+ */
+void f(void)
+{
+ // This is to check...
+ if (y is true)
+ we do b
+
+ /*
+ * We need to do this here
+ * because of ...
+ */
+ for (;;)
+}
+ </div>
+
+ <div class="heading"><h3>Macros, Enums, and RTL</h3></div>
+ Don't align bodies of macros.
+
+ <ul><li>If names are changed or new entries are added, it may produces
+ unnecessary diffs and this makes it harder for you to find lines that are
+ actually modified</li></ul>
+ <div class="code codebox">
+//do this
+#define Anum_ag_graph_name 1
+#define Anum_ag_graph_namespace 2
+
+//not this
+#define Anum_ag_graph_name 1
+#define Anum_ag_graph_namespace 2
+ </div>
+ When you write a macro that spans multiple lines, don't align \ character.
+
+ <ul>
+ <li>If bodies of macros are modified, it may produce unnecessary diffs and
+ this makes it harder for you to find lines that are actually modified.</li>
+ <li>It is harder for you to find lines that are actually modified. </li>
+ </ul>
+ <div class="code codebox">
+// do this
+#define f() \
+ do \
+ { \
+ run(); \
+ } while (0)
+
+// not this
+#define f() \
+ do \
+ { \
+ run(); \
+ } while (0)
+
+ </div>
+
+ <div class="heading"><h3>Newlines</h3></div>
+ For newlines, only \n is allowed, not \r\n and \r.
+
+ <div class="heading"><h3>Conditions</h3></div>
+ If a pointer variable (including List *) is used as a condition, which means that it is
+ evaluated as true/false value, use it AS-IS. Do not perform explicit comparison with
+ NULL (or NIL). For negation, put ! before it.
+
+ <div class="heading"><h3>Rules for ereport()</h3></div>
+ An error message that is passed to <span class="inline-code">errmsg()</span> starts with a lower case letter.
+ <br>
+ An error detail/hint message that is passed to <span class="inline-code">errdetail()/errhint()</span> starts
+ with an upper case letter.
+
+ <!-- END CODING STYLE -->
+ <hr>
+ <!-- BEGIN CREATE DOCS -->
+ <a id="createdocs"></a>
+ <div class="heading"><h2>Creating Documentation</h2></div>
+ <ul>
+ <li>Dependencies: python3, python3-sphinx, sphinx_rtd_theme</li>
+ <li>Clone incubator-age repository (AGE) (https://github.com/apache/incubator-age)</li>
+ <li>Go to the doc folder of the project</li>
+ <li>Type <span class="inline-code">make html</span></li>
+ <li>The documents are in <span class="inline-code">_build/html</span></li>
+ </ul>
+ An example of the commands on Ubuntu follow:
+ <div class="code">
+sudo apt install python3 python3-sphinx
+pip3 install sphinx_rtd_theme
+git clone https://github.com/apache/incubator-age
+cd incubator-age/doc
+make html
+ </div>
+ </div>
+ </div>
+
<!--
*
* COMMUNITY
*
-->
<div class="main-item" id="main-mailinglists">
- <div class="title">Mailing Lists</div>
+ <div class="heading"><h1>Mailing Lists</h1></div>
<div class="main-body">
Get help using Apache AGE (Incubating) or contribute to the project on our mailing lists:
@@ -475,7 +761,7 @@ $$) as (a agtype);
</div>
<div class="main-item" id="main-team">
- <div class="title">Apache AGE Team Members</div>
+ <div class="heading"><h1>Apache AGE Team Members</h1></div>
<div class="main-body">
<div class="subtitle center">✪ Champions and Mentors ✪</div>
<table class="center">