forked from apache/age-website
-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.html
971 lines (876 loc) · 41.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
<!DOCTYPE html>
<html lang="en">
<head>
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-192769708-1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-192769708-1');
</script>
<meta name="description" content="Apache AGE - A Graph Extension for PostgreSQL" />
<meta name="theme-color" content="#ffffff" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" href="assets/styles/index.css" />
<link rel="apple-touch-icon" sizes="180x180" href="assets/images/favicon/apple-touch-icon.png" />
<link rel="icon" type="image/png" sizes="32x32" href="assets/images/favicon/favicon-32x32.png" />
<link rel="icon" type="image/png" sizes="16x16" href="assets/images/favicon/favicon-16x16.png" />
<title>Apache AGE - A Graph Extension for PostgreSQL</title>
<script type="text/javascript" src="assets/scripts/index.js"></script>
</head>
<body>
<div class="root">
<div class="header">
<img src="assets/images/logo.png" width="250px" />
<div class="header--title">A Graph Extension for PostgreSQL</div>
<div class="header--hamburger" id="menu" onclick="handleMenuClick(this)">
<div class="header--hamburger-div"></div>
<div class="header--hamburger-div"></div>
<div class="header--hamburger-div"></div>
</div>
</div>
<div class="sidebar" id="sidebar">
<p class="sidebar--section">
<span class="emph">APACHE AGE</span><br />
<span id="sidebar-overview" class="sidebar-item sidebar--selected"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Overview</a></span> <br />
<!-- FAQs <br /> -->
<span id="sidebar-license" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">License</a></span> <br />
<!-- Downloads <br /> -->
<span id="sidebar-roadmap" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Roadmap</a></span> <br />
</p>
<p class="sidebar--section">
<span class="emph">DOCUMENTATION</span> <br />
<span id="sidebar-installing" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Installing AGE</a></span> <br />
<span id="sidebar-gettingstarted" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Getting Started</a></span> <br />
<!-- <span id="sidebar-ageworks" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">How AGE Works</a></span> <br /> -->
<span id="sidebar-docs" class="sidebar-item"> <a target="_blank" class="sidebar-link" href="docs/">Release Docs</a></span> <br />
<span id="sidebar-guide" class="sidebar-item"> <a target="_blank" class="sidebar-link" href="docs/Apache_AGE_Guide.pdf">AGE Guide (PDF)</a></span> <br />
</p>
<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 />
<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">
<span class="emph">COMMUNITY</span> <br />
<span id="sidebar-team" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Team</a></span> <br />
<span id="sidebar-mailinglists" class="sidebar-item"> <a class="sidebar-link" href="#" onclick="handleClick(this)">Mailing Lists</a></span> <br />
<a class="sidebar-link external-link" target="_blank" href="https://issues.apache.org/jira/projects/AGE/issues">JIRA Issues</a> <br />
<a class="sidebar-link external-link" target="_blank" href="https://github.com/apache/incubator-age">Github</a> <br />
</p>
<p class="sidebar--section">
<span class="emph">ASF</span> <br />
<a class="sidebar-link external-link" target="_blank" href="https://www.apache.org/foundation/">Apache Software Foundation</a> <br />
<a class="sidebar-link external-link" target="_blank" href="https://www.apache.org/foundation/how-it-works.html">How Apache Works</a> <br />
<a class="sidebar-link external-link" target="_blank" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> <br />
<a class="sidebar-link external-link" target="_blank" href="https://www.apache.org/foundation/thanks.html">Thanks</a> <br />
</p>
</div>
<div class="main">
<!--
*
* AGE
*
-->
<div class="main-item main--selected" id="main-overview">
<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 A Graph Extension, and is inspired by Bitnine's fork of
PostgreSQL 10, AgensGraph, which is a multi-model database. The goal of the project is to create single storage that can handle both relational and graph model data
so that users can use standard ANSI SQL along with openCypher, the Graph query language.
</p>
<p>
Below is a brief overview of the AGE architecture in relation to the PostgreSQL architecture and backend.
Every component runs on the PostgreSQL transaction cache layer and storage layer.
<img src="assets/images/ageworks.png">
</p>
<div class="heading"><h2>Features</h2></div>
<ul>
<li>AGE is currently being developed for the PostgreSQL 11 release and will support PostgreSQL 12 and 13 in 2021 and all the future releases of PostgreSQL. </li>
<li>AGE supports the openCypher graph query language and label hierarchy.</li>
<li>AGE enables querying multiple graphs at the same time. This will allow a user to query two or more graphs at once with cypher, decide how to merge them and get the desired query outputs.</li>
<li>AGE will be enhanced with an aim to support all of the key features of AgensGraph (PostgreSQL fork extended with graph DB functionality). </li>
</ul>
</div>
</div>
<div class="main-item" id="main-license">
<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="heading"><h1>Roadmap</h1></div>
<div class="main-body">
<table>
<tbody>
<tr>
<td colspan="2"><b>v0.1.0-alpha</b> ✅</td>
</tr>
<tr>
<td class="tblhead">Release Date</td>
<td>2020 Q1</td>
</tr>
<tr>
<td class="tblhead">Release Notes</td>
<td><a href="https://github.com/apache/incubator-age/releases/tag/v0.1.0">https://github.com/apache/incubator-age/releases/tag/v0.1.0</a></td>
</tr>
<tr>
<td class="tblhead">Functionality</td>
<td>
<ul>
<li>Agtype to support all datatype requirements in Cypher queries</li>
<li>Basic MATCH and CREATE clause support</li>
<li>Expression support</li>
</ul>
</td>
</tr>
</tbody>
</table>
<br>
<table>
<tbody>
<tr>
<td colspan="2"><b>v0.2.0-alpha</b> ✅</td>
</tr>
<tr>
<td class="tblhead">Release Date</td>
<td>2020 Q2</td>
</tr>
<tr>
<td class="tblhead">Release Notes</td>
<td><a href="https://github.com/apache/incubator-age/releases/tag/v0.2.0">https://github.com/apache/incubator-age/releases/tag/v0.2.0</a></td>
</tr>
<tr>
<td class="tblhead">Functionality</td>
<td>
<ul>
<li>Extend Agtype to function better for SQL queries</li>
<li>Scalar functions</li>
<li>Advanced MATCH and CREATE clause support (except for VLE)</li>
</ul>
</td>
</tr>
</tbody>
</table>
<br>
<table>
<tbody>
<tr>
<td colspan="2"><b>v0.3.0-incubating</b> ✅</td>
</tr>
<tr>
<td class="tblhead">Release Date</td>
<td>2021-01-23</td
</tr>
<tr>
<td class="tblhead">Release Notes</td>
<td><a href="https://github.com/apache/incubator-age/releases/tag/v0.3.0.rc0-incubating">https://github.com/apache/incubator-age/releases/tag/v0.3.0.rc0-incubating</a></td>
</tr>
<tr>
<td class="tblhead">Functionality</td>
<td>
<ul>
<li>Aggregation query support</li>
<li>DELETE, SET, REMOVE, MERGE clause support</li>
<li>Label Inheritance</li>
</ul>
</td>
</tr>
</tbody>
</table>
<br>
<table>
<tbody>
<tr>
<td colspan="2"><b>v0.4.0-incubating</b></td>
</tr>
<tr>
<td class="tblhead">Release Date</td>
<td>Target 2021-03-31</td>
</tr>
<tr>
<td class="tblhead">Functionality</td>
<td>
<ul>
<li>Variable Length Edges (VLEs)</li>
<li>Aggregation query support</li>
<li>Client APIs (node.js, Java, Go, ...)</li>
<li>Graph visualization tool integration</li>
<li>PostgreSQL extensions (PL/pgSQL, ...)</li
</ul>
</td>
</tr>
</tbody>
</table>
<br>
<table>
<tbody>
<tr>
<td colspan="2"><b>v0.5.0-incubating</b></td>
</tr>
<tr>
<td class="tblhead">Release Date</td>
<td>Target 2021-05-31</td>
</tr>
<tr>
<td class="tblhead">Release Notes</td>
<td>N/A</td>
</tr>
<tr>
<td class="tblhead">Functionality</td>
<td>
N/A
</td>
</tr>
</tbody>
</table>
<p>* Support for PostgreSQL 12+ and VLE will be added in the later releases in 2021.</p>
</div>
</div>
<!--
*
* DOCUMENTATION
*
-->
<div class="main-item" id="main-installing">
<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>
<li><a class="external-link" target="_blank" href="https://hub.docker.com/r/sorrell/agensgraph-extension">AGE Debian Docker Image</a></li>
<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="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):
<div class="code">$ sudo apt-get install bison build-essential flex postgresql-server-dev-11</div>
The build process will attempt to use the first path in the PATH environment variable when installing AGE.
If the <span class="inline-code">pg_config</span> path if located there, run the following
command in the source code directory of Apache AGE to build and install the extension.
<div class="code">$ make install</div>
If the path to your Postgres installation is not in the PATH variable, add the path in the arguments:
<div class="code">$ make PG_CONFIG=/path/to/postgres/bin/pg_config install</div>
Since Apache AGE will be installed in the directory of the PostgreSQL installation, proper permissions on the directory are required. Run the following statements in
psql to create and load age in PostgreSQL.
<div class="code">=# CREATE EXTENSION age; -- run this statement only once
CREATE EXTENSION
=# LOAD 'age';
LOAD
=# SET search_path = ag_catalog, "$user", public;
SET
</div>
</div>
</div>
<div class="main-item" id="main-gettingstarted">
<div class="heading"><h1>Getting Started</h1></div>
<div class="main-body">
<div class="heading"><h2>Loading AGE</h2></div>
Connect to your containerized Postgres instance and then run the following commands:
<div class="code">
CREATE EXTENSION age;
LOAD 'age';
SET search_path = ag_catalog, "$user", public;
</div>
<div class="heading"><h2>Using AGE</h2></div>
First you will need to create a graph:
<div class="code">
SELECT create_graph('my_graph_name');
</div>
To execute Cypher queries, you will need to wrap them in the following syntax:
<div class="code">
SELECT * from cypher('my_graph_name', $$
CypherQuery
$$) as (a agtype);
</div>
For example, if we wanted to create a graph with 4 nodes, we could do something as shown below:
<div class="code">
SELECT * from cypher('my_graph_name', $$
CREATE (a:Part {part_num: '123'}),
(b:Part {part_num: '345'}),
(c:Part {part_num: '456'}),
(d:Part {part_num: '789'})
$$) as (a agtype);
--- RESULTS
a
---
(0 rows)
</div>
Then we could query the graph with the following:
<div class="code">
SELECT * from cypher('my_graph_name', $$
MATCH (a)
RETURN a
$$) as (a agtype);
--- RESULTS
a
-------------------------------------------------------------------------------------
{"id": 844424930131969, "label": "Part", "properties": {"part_num": "123"}}::vertex
{"id": 844424930131970, "label": "Part", "properties": {"part_num": "345"}}::vertex
{"id": 844424930131971, "label": "Part", "properties": {"part_num": "456"}}::vertex
{"id": 844424930131972, "label": "Part", "properties": {"part_num": "789"}}::vertex
(4 rows)
</div>
Next, we could create a relationship between a couple of nodes:
<div class="code">
SELECT * from cypher('my_graph_name', $$
MATCH (a:Part {part_num: '123'}), (b:Part {part_num: '345'})
CREATE (a)-[u:used_by { quantity: 1 }]->(b)
$$) as (a agtype);
--- RESULTS
a
---
(0 rows)
</div>
Next we can return the path we just created (results have been formatted for readability):
<div class="code">
SELECT * from cypher('age', $$
MATCH p=(a)-[]-(b)
RETURN p
$$) as (a agtype);
// RESULTS
// ROW 1
[
{
"id":844424930131969,
"label":"Part",
"properties":{
"part_num":"123"
}
}::"vertex",
{
"id":1125899906842625,
"label":"used_by",
"end_id":844424930131970,
"start_id":844424930131969,
"properties":{
"quantity":1
}
}::"edge",
{
"id":844424930131970,
"label":"Part",
"properties":{
"part_num":"345"
}
}::"vertex"
]::"path"
// ROW 2
[
{
"id":844424930131970,
"label":"Part",
"properties":{
"part_num":"345"
}
}::"vertex",
{
"id":1125899906842625,
"label":"used_by",
"end_id":844424930131970,
"start_id":844424930131969,
"properties":{
"quantity":1
}
}::"edge",
{
"id":844424930131969,
"label":"Part",
"properties":{
"part_num":"123"
}
}::"vertex"
]::"path"
(2 rows)
</div>
</div>
</div>
<!--
<div class="main-item" id="main-ageworks">
<div class="heading"><h1>How AGE Works</h1></div>
<div class="main-body">
Here is the brief overview of the AGE architecture in which some are related to the PostgreSQL architecture and backend.
Every component runs on the PostgreSQL transaction cache layer and storage layer.
<img src="assets/images/ageworks.png">
</div>
</div> -->
<!--
*
* CONTRIBUTION
*
-->
<div class="main-item" id="main-contribute">
<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="heading"><h2>Becoming a Committer</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="heading"><h2>Contributing by Helping Other Users</h2></div>
A great way to contribute to AGE is to help answer user questions on the mailing list or on StackOverflow.
There are always many new AGE users; taking a few minutes to help answer a question is a very valuable community service.
<br>
Contributors should subscribe to this list and follow it to keep up to date on what's happening in AGE. Answering
questions is an excellent and visible way to help the community, which also demonstrates your expertise.
<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
<span id="inline_contribure-devguidelines"> <a href="#" onclick="handleClick(this)">Developer Guidelines</a></span>).
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="heading"><h2>Contributing Documentation Changes</h2></div>
To propose a change to release documentation (that is, docs that appear <a href="docs/">here</a>),
edit the Markdown source files in AGE's <span class="inline-code">doc/</span>
<a class="external-link" href="https://github.com/apache/incubator-age/tree/master/doc">directory on GitHub</a>.
Instructions for building the documentation can be found
<span id="inline_contribure-devguidelines"> <a href="#createdocs" onclick="handleClick(this)">here</a></span>.
The process to propose a doc change is otherwise the same as the
process for proposing code changes below.
<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>
Bug reports are only useful, however, if they include enough information to understand, isolate and ideally reproduce the bug.
Simply encountering an error does not mean a bug should be reported; search JIRA and inquire on the AGE user / dev mailing
lists first. Unreproducible bugs, or simple error reports, may be closed.
<br>
The more context the reporter can give about a bug, the better, such as: how the bug was introduced, by which
commit, etc. It assists the committers in the decision process on how far the bug fix should be backported,
when the pull request is merged. The pull request to fix the bug should narrow down the problem to the root cause.
<br>
Data correctness/data loss bugs are very serious. Make sure the corresponding bug report JIRA issue is labeled
as correctness or data-loss. Please send an email to <a href="mailto:[email protected]">[email protected]</a> after submitting
the bug report, to quickly draw attention to the issue.
<br>
Performance issues are classified as bugs. The pull request to fix a performance bug must provide a benchmark
to prove the problem is indeed fixed.
<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>
When resolving JIRA tickets, please observe the following conventions:
<ul>
<li>
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 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.
</li>
</ul>
</li>
<li>
For issues that can't be reproduced against master as reported, resolve as Cannot Reproduce.
</li>
<li>
If the issue is the same as or a subset of another issue, resolved as Duplicate
<ul>
<li>
Mark the issue that has less activity or discussion as the duplicate.
</li>
<li>
Link it to the JIRA ticket it duplicates.
</li>
</ul>
</li>
<li>
If the issue seems clearly obsolete and applies to issues or components that have changed radically since it was opened, resolve as Not a Problem
</li>
<li>
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 no support or interest in acting on it, then resolve as Won't Fix.
</li>
</ul>
<br>
<span class="emph">Searching JIRA</span>
How to search JIRA for existing issues:
<ol>
<li><span class="emph">Basic:</span>
<ol>
<li>Visit <a class="external-link" target="_blank" href="https://issues.apache.org/jira/projects/AGE/issues">AGE JIRA</a></li>
<li>Type query into search box in top right (beware this will return results from all projects)</li>
</ol>
</li>
<li>
<span class="emph">Advanced: </span>
<ol>
<li>Visit <a class="external-link" target="_blank" href="https://issues.apache.org/jira/issues/?jql=(project%3DAGE)%20and%20text%20~%20%22%22">AGE JIRA Advanced Search</a></li>
<li>Replace the empty quotes with quoted text (such as "cypher")</li>
</ol>
</li>
<li>
<span class="emph">Search Now:</span>
<ol>
<li>Use the search box below</li>
<li><input class="search" id="jira-search" placeholder="search term"><button class="search external-link" id="jira-submit" onclick="handleJiraSearch()">Search</button></li>
</ol>
</li>
</ol>
If a logically similar issue already exists, then contribute to the discussion on the existing JIRA ticket and pull request, instead of creating a new ticket and PR.
</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 apache/incubator-age.) 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="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:
<ul>
<li>
Visit <a target="_blank" class="external-link" href="https://lists.apache.org/[email protected]">
Commits</a>
or <a class="mail-link" href="mailto:[email protected]">subscribe</a>
for people following commits to the project.
</li>
<li>
Visit <a target="_blank" class="external-link" href="https://lists.apache.org/[email protected]">
Developer</a>
or <a class="mail-link" href="mailto:[email protected]">subscribe</a>
for developers wanting to commit code to the project.
</li>
<li>
Visit <a target="_blank" class="external-link" href="https://lists.apache.org/[email protected]">
Users</a>
or <a class="mail-link" href="mailto:[email protected]">subscribe</a>
for users wanting to learn more about the project.
</li>
</ul>
</div>
</div>
<div class="main-item" id="main-team">
<div class="heading"><h1>Apache AGE Team Members</h1></div>
<div class="main-body">
<div class="heading center"><h2>✪ Mentors ✪</h2></div>
<p class="center">AGE's Mentors are (sorted on last name in alphabetical order):</p>
<table class="center">
<thead>
<tr><th scope="col">Name</th><th scope="col">Email</th></tr>
</thead>
<tbody>
<tr><td>Raphael Bircher</td> <td>rbircher at apache dot org</td></tr>
<tr><td>Von Gosling</td> <td>vongosling at apachedot org</td></tr>
<tr><td>Jim Jagielski</td> <td>jim at apache dot org </td></tr>
<tr><td>Kevin Ratnasekera</td> <td>kevin at agsft dot com</td></tr>
<tr><td>Felix Cheung</td> <td></td></tr>
</tbody>
</table>
<div class="heading center"><h2>✰ Committers ✰</h2></div>
<p class="center">AGE's active Committers are (sorted on last name in alphabetical order):</p>
<table class="center">
<thead>
<tr><th scope="col">Name</th><th scope="col">Email</th></tr>
</thead>
<tbody>
<tr><td>John Gemignani</td> <td>john dot gemignani at bitnine dot net</td></tr>
<tr><td>Josh Innis</td> <td>josh dot innis at bitnine dot net</td></tr>
<tr><td>Eya Badal</td> <td>eya dot abdisho at bitnine dot net</td></tr>
</tbody>
</table>
<div class="heading center"><h2>✧ Contributors ✧</h2></div>
<p class="center">AGE's Contributors are (sorted on last name in alphabetical order):</p>
<table class="center">
<thead>
<tr><th scope="col">Name</th><th scope="col">Email</th></tr>
</thead>
<tbody>
<tr><td>Ghassan Al-Noubani</td> <td>g.noubani at qbs dot jo</td></tr>
<tr><td>Jasper Blues</td> <td>jasper at liberation dash data dot com</td></tr>
<tr><td>Dehowe Feng</td> <td></td></tr>
<tr><td>Donghu Kim</td><td>donghu dot kim at oracle dot com</td></tr>
<tr><td>Andrew Ko</td> <td>andrew dot ko at bitnine dot net</td></tr>
<tr><td>Mason Sharp</td> <td>mason dot sharp at gmail dot com</td></tr>
<tr><td>Muhammad Shoaib</td> <td>Muhammad dot Shoaib at uni dot lu</td></tr>
<tr><td>Nick Sorrell</td> <td>nick at canvouch dot com</td></tr>
<tr><td>Junseok Yang</td> <td></td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>
<img class="footer-img" src="assets/images/incubator_ring_logo.png"> <br>
<p class="center">Copyright © 2021 The Apache Software Foundation. <br>
Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
</body>
</html>