Skip to content

Commit 7cdf672

Browse files
RobRossmiller-TGRobRossmiller-TG
authored
Merge pull request #151 from tigergraph/GML-1718-contributorsguide
Gml 1718 contributorsguide
2 parents 356c36f + 43695f1 commit 7cdf672

File tree

4 files changed

+367
-23
lines changed

4 files changed

+367
-23
lines changed

‎CODE_OF_CONDUCT.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official email address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement by reaching out to one of the contributors
63+
of this repository. All complaints will be reviewed and investigated promptly and fairly.
64+
65+
All community leaders are obligated to respect the privacy and security of the
66+
reporter of any incident.
67+
68+
## Enforcement Guidelines
69+
70+
Community leaders will follow these Community Impact Guidelines in determining
71+
the consequences for any action they deem in violation of this Code of Conduct:
72+
73+
### 1. Correction
74+
75+
**Community Impact**: Use of inappropriate language or other behavior deemed
76+
unprofessional or unwelcome in the community.
77+
78+
**Consequence**: A private, written warning from community leaders, providing
79+
clarity around the nature of the violation and an explanation of why the
80+
behavior was inappropriate. A public apology may be requested.
81+
82+
### 2. Warning
83+
84+
**Community Impact**: A violation through a single incident or series of
85+
actions.
86+
87+
**Consequence**: A warning with consequences for continued behavior. No
88+
interaction with the people involved, including unsolicited interaction with
89+
those enforcing the Code of Conduct, for a specified period of time. This
90+
includes avoiding interactions in community spaces as well as external channels
91+
like social media. Violating these terms may lead to a temporary or permanent
92+
ban.
93+
94+
### 3. Temporary Ban
95+
96+
**Community Impact**: A serious violation of community standards, including
97+
sustained inappropriate behavior.
98+
99+
**Consequence**: A temporary ban from any sort of interaction or public
100+
communication with the community for a specified period of time. No public or
101+
private interaction with the people involved, including unsolicited interaction
102+
with those enforcing the Code of Conduct, is allowed during this period.
103+
Violating these terms may lead to a permanent ban.
104+
105+
### 4. Permanent Ban
106+
107+
**Community Impact**: Demonstrating a pattern of violation of community
108+
standards, including sustained inappropriate behavior, harassment of an
109+
individual, or aggression toward or disparagement of classes of individuals.
110+
111+
**Consequence**: A permanent ban from any sort of public interaction within the
112+
community.
113+
114+
## Attribution
115+
116+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
117+
version 2.1, available at
118+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
119+
120+
Community Impact Guidelines were inspired by
121+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
122+
123+
For answers to common questions about this code of conduct, see the FAQ at
124+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
125+
[https://www.contributor-covenant.org/translations][translations].
126+
127+
[homepage]: https://www.contributor-covenant.org
128+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
129+
[Mozilla CoC]: https://github.com/mozilla/diversity
130+
[FAQ]: https://www.contributor-covenant.org/faq
131+
[translations]: https://www.contributor-covenant.org/translations
132+

‎CONTRIBUTING.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Contribution Guidelines
2+
3+
## Issues
4+
If you discover an issue with an algorithm, or test, open an issue to point out areas for improvement.
5+
If you are comfortable with it, implement the fix and open a PR.
6+
7+
8+
## Adding tests
9+
See the [testing contributors guide](tests/CONTRIBUTING.md)
10+
11+
## Coding Standards
12+
13+
### Languages
14+
15+
*GSQL*
16+
- Follow the [GSQL Style Guide](https://docs.tigergraph.com/gsql-ref/current/appendix/gsql-style-guide)
17+
18+
*Python*
19+
- Use the [ruff formatter](https://docs.astral.sh/ruff/formatter/#the-ruff-formatter) to format your code
20+
- tests: pytest and networkx wherever applicable
21+
22+
*C/CPP*
23+
24+
25+
## Pull Requests
26+
- Make sure git knows your name and email address:
27+
```
28+
$ git config user.name "J. Random User"
29+
$ git config user.email "[email protected]"
30+
```
31+
- The name and email address must be valid as we cannot accept anonymous contributions.
32+
- Write good commit messages.
33+
- Concise commit messages that describe your changes help us better understand your contributions.
34+
35+
## General Guidelines
36+
37+
Ensure your pull request (PR) adheres to the following guidelines:
38+
39+
- Try to make the name concise and descriptive.
40+
- Give a good description of the change being made. Since this is very subjective, see the [Updating Your Pull Request (PR)](#updating-your-pull-request-pr) section below for further details.
41+
- Every pull request should be associated with one or more issues. If no issue exists yet, please create your own.
42+
- Make sure that all applicable issues are mentioned somewhere in the PR description. This can be done by typing # to bring up a list of issues.
43+
44+
### Updating Your Pull Request (PR)
45+
46+
A lot of times, making a PR adhere to the standards above can be difficult. If the maintainers notice anything that we'd like changed, we'll ask you to edit your PR before we merge it.
47+
This applies to both the content documented in the PR and the changed contained within the branch being merged. There's no need to open a new PR. Just edit the existing one.
48+
49+
---
50+
51+
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
52+

‎tests/CONTRIBUTING.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Contribution Guidelines for Adding Tests
2+
3+
### Contents
4+
5+
- [Running the tests](#running-the-tests)
6+
- [Directory Layout](#directory-layout)
7+
- [Adding tests](#adding-tests)
8+
- [Available Graphs](#available-graphs)
9+
10+
## Running the tests
11+
12+
Execute the following to download the dependencies and run the tests. Make sure you're in a venv.
13+
14+
```sh
15+
echo '
16+
HOST_NAME="https://tg-hostname"
17+
USER_NAME=tigergraph
18+
PASS=tigergraph
19+
' >> test/.env
20+
pip install -r requirements.txt
21+
./run.sh
22+
```
23+
24+
`test/.env`
25+
26+
- HOST_NAME: A TG environment that you have querywriter access to so setup.py can load data and queries to a subgraph named `graph_algorithms_testing`
27+
- USER_NAME: user
28+
- PASS: user's password
29+
30+
`run.sh` does a few things:
31+
32+
- runs `data/create_baseline.py`
33+
- this creates the baselines from the graphs listed in that file
34+
- runs the setup script to make sure the graph is created and data is loaded
35+
- runs the tests with pytest
36+
37+
## Directory layout
38+
39+
Data: stores the satic data for creating graphs, and algorithm baseline results.
40+
41+
- CSV files under `data/[heterogeneous_edges, unweighted_edges, weighted_edges]` store the adjacency information for creating graphs. The baselines for algorithms are made from these graphs
42+
- For example `data/weighted_edges/line_edges.csv` stores the edges and weights to create a weighted, line graph.
43+
- JSON files under `data/baseline` store the baseline results for a given algorithm on a given graph type.
44+
- For example `data/baseline/centrality/pagerank/Line_Directed.json` stores the baseline results for pagerank on a directed line graph
45+
46+
test:
47+
48+
- setup.py: creates the graph, loads the data and installs the queries from pyTG's featurizer. Any new/custom queries need to be manually installed
49+
- test<algo_family>.py: houses the testing code for each family of algorithms
50+
51+
```
52+
├── data
53+
│   ├── baseline
54+
│   │   ├── <algo_family>
55+
│   │   │   └── <algo_name>
56+
│   │ │ └── <GraphType>.json
57+
│   ├── <edge_family>
58+
│   │ └── <graph_type>.csv
59+
│   └── create_baseline.py
60+
├── requirements.txt
61+
├── run.sh
62+
├── test
63+
│   ├── pyrightconfig.json
64+
│   ├── setup.py
65+
│   ├── test_centrality.py
66+
│   ├── test_community.py
67+
│   ├── test_path_finding.py
68+
│   ├── test_topological_link_prediction.py
69+
│   └── util.py
70+
```
71+
72+
## Adding tests
73+
74+
Start with creating the baseline. Add a section to `create_baseline.py` that creates a baseline for all the necessary graph types for your algorithm. The output of the baseline should be written to
75+
the correct baseline path (see above [layout](#directory-layout)).
76+
77+
If you're adding a new algorithm, add a test method for it to the algorithm family that it belongs to (i.e., community algorigthms go in community.py). The first test method in `test/test_centrality.py`
78+
is a good template to follow:
79+
80+
```py
81+
# this function will run once for each of the graph names in the undirected_graphs list
82+
@pytest.mark.parametrize("test_name", undirected_graphs)
83+
def test_degree_centrality1(self, test_name):
84+
# query params
85+
params = {
86+
"v_type_set": ["V20"],
87+
"e_type_set": [test_name],
88+
"reverse_e_type_set": [test_name],
89+
"in_degree": True,
90+
"out_degree": False,
91+
"top_k": 100,
92+
"print_results": True,
93+
"result_attribute": "",
94+
"file_path": "",
95+
}
96+
with open(f"data/baseline/centrality/degree_centrality/{test_name}.json") as f:
97+
baseline = json.load(f)
98+
baseline = sorted(baseline[0]["top_scores"], key=lambda x: x["Vertex_ID"])
99+
100+
# call the the algorithm through the featurizer
101+
result = self.feat.runAlgorithm("tg_degree_cent", params=params)
102+
result = sorted(result[0]["top_scores"], key=lambda x: x["Vertex_ID"])
103+
104+
105+
# check that the results agree with the baseline
106+
for b in baseline:
107+
for r in result:
108+
if r["Vertex_ID"] == b["Vertex_ID"] and r["score"] != pytest.approx(
109+
b["score"]
110+
):
111+
pytest.fail(f'{r["score"]} != {b["score"]}')
112+
```
113+
114+
## Available Graphs
115+
116+
Example usage:
117+
118+
- If you want to run a query on a directed, weighted, line graph, use the V20 verts and Line_Directed_Weighted edges.
119+
120+
| Graph | Type | Vertices | Edges |
121+
| --------------------------- | ------------------------------------------------------------ | -------- | -------------------------------- |
122+
| Null | | V0 | |
123+
| Single node | | V1 | |
124+
| Empty graph | Undirected | V20 | Empty |
125+
| | Directed | | Empty_Directed |
126+
| Line | Undirected, unweighted | V20 | Line |
127+
| | Directed, unweighted | | Line_Directed |
128+
| | Undirected, weighted | | Line_Weighted |
129+
| | Directed, weighted | | Line_Directed_Weighted |
130+
| | Heterogeneous vertex types, directed, weighted | V20, V8 | Line_Heterogeneous |
131+
| Ring | Undirected, unweighted | V20 | Ring |
132+
| | Directed, unweighted | | Ring_Directed |
133+
| | Undirected, weighted | | Ring_Weighted |
134+
| | Directed, weighted | | Ring_Directed_Weighted |
135+
| | Heterogeneous vertex types, directed, weighted | V20, V8 | Ring_Heterogeneous |
136+
| Hub & spoke | Undirected, unweighted | V20 | Hub_Spoke |
137+
| | Directed (towards the spokes), unweighted Hub_Spoke_Directed | | |
138+
| | Undirected, weighted Hub_Spoke_Weighted | | |
139+
| | Directed, weighted Hub_Spoke_Directed_Weighted | | |
140+
| | Heterogeneous vertex types, directed, weighted | V20, V8 | Hub_Spoke_Heterogeneous |
141+
| Hub-connected hub & spoke | Undirected, unweighted | V20 | Hub_Connected_Hub_Spoke |
142+
| | Undirected, weighted | | Hub_Connected_Hub_Spoke_Weighted |
143+
| Tree | Undirected, unweighted | V20 | Tree |
144+
| | Directed, unweighted | | Tree_Directed |
145+
| | Undirected, weighted | | Tree_Weighted |
146+
| | Directed, weighted | | Tree_Directed_Weighted |
147+
| | Heterogeneous vertex types, directed, weighted | V20, V8 | Tree_Heterogeneous |
148+
| Complete | Undirected, unweighted | V8 | Complete |
149+
| | Directed, unweighted | | Complete_Directed |
150+
| | Undirected, weighted | | Complete_Weighted |
151+
| | Directed, weighted | | Complete_Directed_Weighted |
152+
| | Heterogeneous vertex types, directed, weighted | V4, V8 | Complete_Heterogeneous |
153+
| DAG | Directed, unweighted | V20 | DAG_Directed |
154+
| | Directed, weighted | | DAG_Directed_Weighted |
155+
| | Heterogeneous vertex types, directed, weighted | V20, V8 | DAG_Heterogeneous |
156+
| Graph with negative cycles | Directed, weighted | V20 | Negative_cycles |
157+
| | Heterogeneous vertex types, directed, weighted | V20, V8 | Negative_Cycle_Heterogeneous |
158+
| Topological link prediction | Unweighted, undirected | V8 | topo_link1 |
159+
| | topo_link2 | | |
160+
| | topo_link3 | | |
161+
| | topo_link4 | | |
162+
| | topo_link5 | | |
163+
| | topo_link6 | | |
164+
| | Unweighted, directed | | topo_link_directed |
165+
| Same Community | no edges | V4 | |

0 commit comments

Comments
 (0)