This is an automated email from the ASF dual-hosted git repository.
weibin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-graphar.git
The following commit(s) were added to refs/heads/main by this push:
new 2c57f16 docs: Update CONTRIBUTING.md and READMEs (#458)
2c57f16 is described below
commit 2c57f16e9b894a5e9327773f87a439db91447a2b
Author: Weibin Zeng <[email protected]>
AuthorDate: Tue Apr 23 13:54:21 2024 +0800
docs: Update CONTRIBUTING.md and READMEs (#458)
related issue #432
- Update `CONTRIBUTING` and `README`
- Update the related template for pull request and issues
---------
Signed-off-by: acezen <[email protected]>
---
.github/ISSUE_TEMPLATE/bug_report.yml | 82 ++----
.github/ISSUE_TEMPLATE/feature_request.md | 20 --
.github/ISSUE_TEMPLATE/feature_request.yml | 49 ++++
.github/PULL_REQUEST_TEMPLATE.md | 51 +++-
CONTRIBUTING.md | 112 ++++++++
CONTRIBUTING.rst | 440 -----------------------------
README.md | 70 ++---
cpp/README.md | 24 +-
8 files changed, 245 insertions(+), 603 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml
b/.github/ISSUE_TEMPLATE/bug_report.yml
index e06d1f0..8a2dd65 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -15,72 +15,32 @@
# specific language governing permissions and limitations
# under the License.
-name: 🐞 Bug Report
-description: File a new bug report
-title: '[Bug]: <title>'
-labels: [Bug]
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+assignees: []
body:
- - type: markdown
- attributes:
- value: ':stop_sign: _For support questions, please visit [GraphAr
Discussions](https://github.com/apache/incubator-graphar/discussions) instead._'
- - type: checkboxes
- attributes:
- label: 'Is there an existing issue for this?'
- description: 'Please [search :mag: the
issues](https://github.com/apache/incubator-graphar/issues) to check if this
bug has already been reported.'
- options:
- - label: 'I have searched the existing issues'
- required: true
- type: textarea
+ id: description
attributes:
- label: 'Current Behavior'
- description: 'Describe the problem you are experiencing. **Please do
not paste your logs here.** Screenshots are welcome.'
+ label: Describe the bug, including details regarding any error messages,
version, and platform.
+ description: Please include what you expected.
validations:
required: true
- - type: textarea
+ - type: dropdown
+ id: component
attributes:
- label: 'Expected Behavior'
- description: 'Describe what you expect to happen instead.'
- validations:
- required: true
- - type: textarea
- attributes:
- label: 'Minimal Reproducible Example'
- description: |
- Please provide a the _smallest, complete code snippet_ that GraphAr's
maintainers can run to reproduce the issue ([read more about what this
entails](https://stackoverflow.com/help/minimal-reproducible-example)).
Failing this, any sort of reproduction steps are better than nothing!
-
- If the result is more than a screenful of text _or_ requires multiple
files, please:
-
- - _Attach_ (do not paste) it to this textarea, _or_
- - Put it in a [Gist](https://gist.github.com) and paste the link, _or_
- - Provide a link to a new or existing public repository exhibiting the
issue
+ label: Component(s)
+ multiple: true
+ options:
+ - Format
+ - C++
+ - Java
+ - Spark
+ - PySpark
+ - Continuous Integration
+ - Developer Tools
+ - Documentation
+ - Other
validations:
required: true
- - type: textarea
- attributes:
- label: 'Environment'
- description: 'Please provide the following information about your
environment; feel free to remove any items which are not relevant.'
- value: |
- - Operating system:
- - GraphAr version:
- validations:
- required: false
- - type: input
- attributes:
- label: 'Link to GraphAr Logs'
- description: |
- Create a [Gist](https://gist.github.com)—which contains your _full_
GraphAr logs—and link it here. Alternatively, you can attach a logfile to this
issue (drag it into the "Further Information" field below).
-
- :warning: _Remember to redact or remove any sensitive information!_
- placeholder: 'https://gist.github.com/...'
- - type: textarea
- attributes:
- label: Further Information
- description: |
- Links? References? Anything that will give us more context about the
issue you are encountering!
-
- _Tip: You can attach images or log files by clicking this area to
highlight it and then dragging files in._
- validations:
- required: false
- - type: markdown
- attributes:
- value: ':stop_sign: _For support questions, please visit [GraphAr
Discussions](https://github.com/apache/incubator-graphar/discussions) instead._'
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md
b/.github/ISSUE_TEMPLATE/feature_request.md
deleted file mode 100644
index ff37e98..0000000
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: '[Feat]'
-labels: 'enhancement'
-assignees: ''
-
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always
frustrated when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features
you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml
b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..891902d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,49 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you 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.
+
+name: Enhancement Request
+description: Request an enhancement to the project
+labels: ["enhancement"]
+assignees: []
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to share your feedback on ways Apache
GraphAr (incubating) can be improved!
+ - type: textarea
+ id: description
+ attributes:
+ label: Describe the enhancement requested
+ validations:
+ required: true
+ - type: dropdown
+ id: component
+ attributes:
+ label: Component(s)
+ multiple: true
+ options:
+ - Format
+ - C++
+ - Java
+ - Spark
+ - PySpark
+ - Continuous Integration
+ - Developer Tools
+ - Documentation
+ - Other
+ validations:
+ required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 95a8f0b..f8c05e7 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,18 +1,47 @@
-## Proposed changes
+<!--
+Thanks for contributing to GraphAr.
+If this is your first pull request you can find detailed information on
[CONTRIBUTING.md](https://github.com/apache/graphar/blob/main/CONTRIBUTING.md)
-Describe the big picture of your changes here to communicate to the
maintainers why we should accept this pull request. If it fixes a bug or
resolves a feature request, be sure to link to that issue.
+The Apache GraphAr (incubating) community has restrictions on the naming of pr
title. You can find instructions in
+[CONTRIBUTING.md](https://github.com/apache/graphar/blob/main/CONTRIBUTING.md#title)
too.
+-->
-## Checklist
+### Reason for this PR
+<!--
+Why are you proposing this change? If this is already tracked in an issue,
please link to the issue here.
+Explaining clearly why this change is beneficial is important for the
reviewers to understand the context.
+-->
-_Put an `x` in the boxes that apply. You can also fill these out after
creating the PR. If you're unsure about any of them, don't hesitate to ask.
We're here to help! This is simply a reminder of what we are going to look for
before merging your code._
-- [ ] I have read the
[CONTRIBUTING](https://github.com/apache/incubator-graphar/blob/main/CONTRIBUTING.rst)
doc
-- [ ] I have signed the CLA
-- [ ] Lint and unit tests pass locally with my changes
-- [ ] I have added tests that prove my fix is effective or that my feature
works
-- [ ] I have added necessary documentation (if appropriate)
+### What changes are included in this PR?
+<!--
+There is no need to duplicate the description in the issue here but it is
sometimes worth providing a summary of the individual changes in this PR.
+-->
-## Further comments
+### Are these changes tested?
+<!--
+We typically require tests for all PRs in order to:
+1. Prevent the code from being accidentally broken by subsequent changes
+2. Serve as another way to document the expected behavior of the code
-If this is a relatively large or complex change, kick off the discussion by
explaining why you chose the solution you did and what alternatives you
considered, etc...
+If tests are not included in your PR, please explain why (for example, are
they covered by existing tests)?
+-->
+### Are there any user-facing changes?
+<!--
+If there are user-facing changes then we may require documentation to be
updated before approving the PR.
+-->
+
+<!--
+If there are any breaking changes to public APIs, please uncomment the line
below and explain which changes are breaking.
+-->
+<!-- **BREAKING CHANGE: <description>** -->
+
+<!--
+Please uncomment the line below (and provide explanation) if the changes fix
either
+(a) a security vulnerability,
+(b) a bug that caused incorrect or invalid data to be produced, or
+(c) a bug that causes a crash (even when the API contract is upheld).
+We use this to highlight fixes to issues that may affect users without their
knowledge. For this reason, fixing bugs that cause errors don't count, since
those are usually obvious.
+-->
+<!-- **Critical Fix: <description>** -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..02b8f18
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,112 @@
+# Contributing to GraphAr
+
+First off, thank you for considering contributing to GraphAr. It's
+people like you that make GraphAr better and better.
+
+There are many ways to contribute, from improving the documentation,
+submitting bug reports and feature requests or writing code which can
+be incorporated into GraphAr itself.
+
+- [Contributing to GraphAr](#contributing-to-graphar)
+ - [Code of Conduct](#code-of-conduct)
+ - [First Contribution](#first-contribution)
+ - [Workflow](#workflow)
+ - [Create a branch](#create-a-branch)
+ - [GitHub Pull Requests](#github-pull-requests)
+ - [Title](#title)
+ - [Reviews & Approvals](#reviews--approvals)
+ - [Merge Style](#merge-style)
+ - [CI](#ci)
+ - [Setup Development Environment](#setup-development-environment)
+ - [Using a dev container environment](#using-a-dev-container-environment)
+ - [Use your own toolkit](#use-your-own-toolkit)
+
+## Code of Conduct
+
+We expect all community members to follow our [Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html).
+
+## First Contribution
+
+1. Ensure your change has an issue! Find an [existing
issue](https://github.com/apache/graphar/issues) or [open a new
issue](https://github.com/apache/graphar/issues/new).
+1. [Fork the GraphAr repository](https://github.com/apache/graphar/fork) in
your own GitHub account.
+1. [Create a new Git
branch](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository).
+1. Make your changes.
+1. [Submit the branch as a pull
request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)
to the main GraphAr repo. An GraphAr team member should comment and/or review
your pull request within a few days. Although, depending on the circumstances,
it may take longer.
+1. Discussing and keeping your Pull Request updated.
+
+ You will probably get feedback or requests for changes to your pull
request. This is a big part of the submission process so don't be discouraged!
It is a necessary part of the process in order to evaluate whether the changes
are correct and necessary.
+
+ Feel free to post a comment in the pull request to ping reviewers if you
are awaiting an answer on something. If you encounter words or acronyms that
seem unfamiliar, refer to this
[glossary](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/glossary.md).
+
+## Workflow
+
+### Create a branch
+
+*All* changes has to be made in a branch and submitted as [pull
requests](#github-pull-requests).
+
+A good branch name would be the issue number you are working on and a short
description of the change,
+like (where issue \#42 is the ticket you're working on):
+
+``` shell
+$ git checkout -b 42-add-chinese-translations
+```
+
+### GitHub Pull Requests
+
+Once your changes are ready you must submit your branch as a [pull request](
+https://github.com/apache/graphar/pulls)
+
+#### Title
+
+The pull request title must follow the format outlined in the [conventional
commits spec](https://www.conventionalcommits.org).
+
+[Conventional commits](https://www.conventionalcommits.org) is a standardized
format for commit messages.
+GraphAr only requires this format for commits on the `main` branch. And
because GraphAr squashes commits before merging branches, this means that only
the pull request title must conform to this format.
+
+The following are all good examples of pull request titles:
+
+```text
+feat(c++): Support timestamp data type
+docs: fix the images link of README
+ci: Mark job as skipped if owner is not apache
+fix(c++): Fix the bug of the memory leak
+refactor: Refactor the API of the vertex info implementation
+```
+
+#### Reviews & Approvals
+
+All pull requests should be reviewed by at least one GraphAr committer.
+
+#### Merge Style
+
+All pull requests are squash merged.
+We generally discourage large pull requests that are over 300–500 lines of
diff.
+If you would like to propose a change that is larger, we suggest
+coming onto our [Discussions](https://github.com/apache/graphar/discussions)
and discussing it with us.
+This way we can talk through the solution and discuss if a change that large
is even needed!
+This will produce a quicker response to the change and likely produce code
that aligns better with our process.
+
+### CI
+
+Currently, GraphAr uses GitHub Actions to run tests. The workflows are defined
in `.github/workflows`.
+
+## Setup Development Environment
+
+For small or first-time contributions, we recommend the dev container method.
And if you prefer to do it yourself, that's fine too!
+
+### Using a dev container environment
+
+GraphAr provides a pre-configured [dev container](https://containers.dev/)
+that could be used in [GitHub
Codespaces](https://github.com/features/codespaces),
+[VSCode](https://code.visualstudio.com/docs/devcontainers/containers),
[JetBrains](https://www.jetbrains.com/remote-development/gateway/),
+[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/).
+Please pick up your favorite runtime environment.
+
+### Use your own toolkit
+
+Different components of GraphAr may require different setup steps. Please
refer to their respective `README` documentation for more details.
+
+- [C++ Library](cpp/README.md)
+- [Java Library](java/README.md)
+- [Spark Library](spark/README.md)
+- [PySpark Library](pyspark/README.md)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
deleted file mode 100644
index 3b6343c..0000000
--- a/CONTRIBUTING.rst
+++ /dev/null
@@ -1,440 +0,0 @@
-Contributing to GraphAr
-========================
-
-First off, thank you for considering contributing to GraphAr. It's people like
you that make GraphAr better and better.
-
-GraphAr is an open source project and we love to receive contributions from
our community — you!
-There are many ways to contribute, from improving the documentation,
submitting bug reports and
-feature requests or writing code which can be incorporated into GraphAr itself.
-
-Note that no matter how you contribute, your participation is governed by our
`Code of Conduct`_.
-
-Reporting bug
--------------------
-
-If you've noticed a bug in GraphAr, first make sure that you are testing
against
-the `latest version of GraphAr
<https://github.com/apache/incubator-graphar/tree/main>`_ -
-your issue may already have been fixed. If not, search our `issues list
<https://github.com/apache/incubator-graphar/issues>`_
-on GitHub in case a similar issue has already been opened.
-
-If you get confirmation of your bug, `file a bug issue`_ before starting to
code.
-
-Requesting feature or enhancement
----------------------------------------
-
-If you find yourself wishing for a feature that doesn't exist in GraphAr, you
are probably not alone.
-There are bound to be others out there with similar needs. Many of the
features that GraphAr has today
-have been added because our users saw the need.
-
-`Open a feature request issue`_ on GitHub which describes the feature you would
-like to see, why you need it, and how it should work.
-
-Support questions
------------------
-If you have a general question about GraphAr, please don't use the issue
tracker for that.
-The issue tracker is a tool to address bugs and feature requests in GraphAr
itself.
-Use our `Github Discussions`_ for questions about using GraphAr or issues with
your own code:
-
-
-Contributing code and documentation changes
--------------------------------------------
-
-If you would like to contribute a new feature or a bug fix to GraphAr,
-please discuss your idea first on the GitHub issue. If there is no GitHub issue
-for your idea, please open one. It may be that somebody is already working on
-it, or that there are particular complexities that you should know about before
-starting the implementation. There are often a number of ways to fix a problem
-and it is important to find the right approach before spending time on a PR
-that cannot be merged.
-
-Install pre-commit
-^^^^^^^^^^^^^^^^^^
-
-GraphAr use `pre-commit`_ to ensure no secrets are accidentally committed
-into the Git repository, you could first install `pre-commit`_ by
-
-.. code:: bash
-
- $ pip3 install pre-commit
-
-The configure the necessary pre-commit hooks with
-
-.. code:: bash
-
- $ pre-commit install --install-hooks
-
-Minor Fixes
-^^^^^^^^^^^^
-
-Any functionality change should have a GitHub issue opened. For minor changes
that
-affect documentation, you do not need to open up a GitHub issue. Instead you
can
-prefix the title of your PR with "[MINOR] " if meets the following guidelines:
-
-* Grammar, usage and spelling fixes that affect no more than 2 files
-* Documentation updates affecting no more than 2 files and not more
- than 500 words.
-
-Fork & create a branch
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-You will need to fork the main GraphAr code and clone it to your local
machine. See
-`github help page <https://help.github.com/articles/fork-a-repo>`_ for help.
-
-Then you need to create a branch with a descriptive name.
-
-A good branch name would be (where issue #42 is the ticket you're working on):
-
-.. code:: shell
-
- $ git checkout -b 42-add-chinese-translations
-
-Get the test suite running
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Now initialize the submodules of GraphAr:
-
-.. code:: shell
-
- $ git submodule update --init
-
-For the C++ Library, Check that the system has the `GraphAr C++ Dependencies`_.
-
-Then you can do an out-of-source build using CMake and build the test suite:
-
-.. code:: shell
-
- $ mkdir build
- $ cd build
- $ cmake ../cpp -DBUILD_TESTS=ON
- $ make -j$(nproc)
-
-Now you should be able to run the test suite:
-
-.. code:: shell
-
- $ make test
-
-For the Spark Library, Check that the system has the `GraphAr Spark
Dependencies`_.
-
-Then you build and run test suite using Maven:
-
-.. code:: shell
-
- $ cd spark
- $ mvn test
-
-How to generate the document
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you want to improve the document, you need to know how to generate the docs.
-
-The documentation is generated using Doxygen and sphinx. For sphinx and other
Python dependency the GraphAr pyspark subproject is used. You need to `install
Poetry packaging system first <https://python-poetry.org/docs/#installation>`_.
The next step will be installation of docs-related Python dependencies:
-
-.. code:: shell
- $ cd pyspark
- $ poetry install --with=docs
-
-.. note::
- If you want to update PySpark project API documentation, you need also
install dependencies from spark group in poetry: poetry install
--with=docs,spark. For Cpp API documentation you need to `install also doxygen
<https://www.doxygen.nl/manual/install.html>`_ (in most of POSIX-compatible
systems installation is also possible via system package manager). For
Java/Scala API documentation you need to `install Maven
<https://maven.apache.org/install.html>`_ (this step also may be done vi [...]
-
-After that you can build GraphAr's documentation in the :code:`docs/`
directory using:
-
-.. code:: shell
-
- $ cd docs
- $ make html
-
-The HTML documentation will be available under ``docs/_build/html``.
-
-Implement your fix or feature
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-At this point, you're ready to make your changes! Feel free to ask for help;
-everyone is a beginner at first :smile_cat:
-
-Get the code format & style right
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Your patch should follow the same conventions & pass the same code quality
-checks as the rest of the project which follows the `Google C++ Style Guide
<https://google.github.io/styleguide/cppguide.html>`_.
-
-You can format your code by the command:
-
-.. code:: shell
-
- $ cd build
- $ make gar-clformat
-
-You can check & fix style issues by running the *cpplint* linter with the
command:
-
-.. code:: shell
-
- $ cd build
- $ make gar-cpplint
-
-Submitting your changes
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Once your changes and tests are ready to submit for review:
-
-1. Test you changes
-
-Run the test suite to make sure that nothing is broken.
-
-2. Sign the Contributor License Agreement (CLA)
-
-Please make sure you have signed our `Contributor License Agreement`_.
-We are not asking you to assign copyright to us, but to give us the right to
distribute your code without restriction.
-We ask this of all contributors in order to assure our users of the origin and
continuing existence of the code. You only need to sign the CLA once.
-
-3. Submit a pull request
-
-At this point, you should switch back to your main branch and make sure it's
-up to date with GraphAr's main branch:
-
-.. code:: shell
-
- $ git remote add upstream https://github.com/apache/incubator-graphar.git
- $ git checkout main
- $ git pull upstream main
-
-Then update your feature branch from your local copy of main, and push it!
-
-.. code:: shell
-
- $ git checkout 42-add-chinese-translations
- $ git rebase main
- $ git push --set-upstream origin 42-add-chinese-translations
-
-Finally, go to GitHub and `make a Pull Request`_ :D
-
-Github Actions will run our test suite against different environments. We
-care about quality, so your PR won't be merged until all tests pass.
-
-Discussing and keeping your Pull Request updated
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You will probably get feedback or requests for changes to your pull request.
-This is a big part of the submission process so don't be discouraged!
-It is a necessary part of the process in order to evaluate whether the changes
-are correct and necessary.
-
-If a maintainer asks you to "rebase" your PR, they're saying that a lot of code
-has changed, and that you need to update your branch so it's easier to merge.
-
-To learn more about rebasing in Git, there are a lot of `good
<http://git-scm.com/book/en/Git-Branching-Rebasing>`_
-`resources <https://help.github.com/en/github/using-git/about-git-rebase>`_,
but here's the suggested workflow:
-
-.. code:: shell
-
- $ git checkout 42-add-chinese-translations
- $ git pull --rebase upstream main
- $ git push --force-with-lease 42-add-chinese-translations
-
-Feel free to post a comment in the pull request to ping reviewers if you are
awaiting an answer
-on something. If you encounter words or acronyms that seem unfamiliar, refer
to this `glossary`_.
-
-Merging a PR (maintainers only)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A PR can only be merged into main by a maintainer if:
-
-* It is passing CI.
-* It has been approved by at least two maintainers. If it was a maintainer who
- opened the PR, only one extra approval is needed.
-* It has no requested changes.
-* It is up to date with current main.
-
-Any maintainer is allowed to merge a PR if all of these conditions are
-met.
-
-.. the reviewing part document is referred and derived from
-..
https://github.com/nodejs/node/blob/main/doc/contributing/pull-requests.md#the-process-of-making-changes
-
-Reviewing pull requests
------------------------
-
-All contributors who choose to review and provide feedback on Pull Requests
have
-a responsibility to both the project and the individual making the
contribution.
-Reviews and feedback must be helpful, insightful, and geared towards improving
-the contribution as opposed to simply blocking it. Do not expect to be able to
-block a pull request from advancing simply because you say "No" without giving
-an explanation. Be open to having your mind changed. Be open to working with
the
-contributor to make the pull request better.
-
-Reviews that are dismissive or disrespectful of the contributor or any other
-reviewers are strictly counter to the `Code of Conduct`_ and will not be
tolerated.
-
-When reviewing a pull request, the primary goals are for the codebase to
improve
-and for the person submitting the request to succeed. Even if a pull request
does
-not land, the submitters should come away from the experience feeling like
their
-effort was not wasted or unappreciated. Every pull request from a new
contributor
-is an opportunity to grow the community.
-
-Review a bit at a time
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Do not overwhelm new contributors.
-
-It is tempting to micro-optimize and make everything about relative
performance,
-perfect grammar, or exact style matches. Do not succumb to that temptation.
-
-Focus first on the most significant aspects of the change:
-
-1. Does this change make sense for GraphAr?
-2. Does this change make GraphAr better, even if only incrementally?
-3. Are there clear bugs or larger scale issues that need attending to?
-4. Is the commit message readable and correct? If it contains a breaking change
- is it clear enough?
-
-When changes are necessary, *request* them, do not *demand* them, and do not
-assume that the submitter already knows how to add a test or run a benchmark.
-
-Specific performance optimization techniques, coding styles, and conventions
-change over time. The first impression you give to a new contributor never
does.
-
-Nits (requests for small changes that are not essential) are fine, but try to
-avoid stalling the pull request. Most nits can typically be fixed by the
-GraphAr collaborator landing the pull request but they can also be an
-opportunity for the contributor to learn a bit more about the project.
-
-It is always good to clearly indicate nits when you comment: e.g.
-:code:`Nit: change foo() to bar(). But this is not blocking.`
-
-If your comments were addressed but were not folded automatically after new
-commits or if they proved to be mistaken, please, `hide them
<https://docs.github.com/en/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment>`_
-with the appropriate reason to keep the conversation flow concise and relevant.
-
-Be aware of the person behind the code
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Be aware that *how* you communicate requests and reviews in your feedback can
-have a significant impact on the success of the pull request. Yes, we may land
-a particular change that makes GraphAr better, but the individual might just
-not want to have anything to do with GraphAr ever again. The goal is not just
-having good code.
-
-Respect the minimum wait time for comments
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There is a minimum waiting time which we try to respect for non-trivial
-changes, so that people who may have important input in such a distributed
-project are able to respond.
-
-For non-trivial changes, pull requests must be left open for at least 48 hours.
-Sometimes changes take far longer to review, or need more specialized review
-from subject-matter experts. When in doubt, do not rush.
-
-Trivial changes, typically limited to small formatting changes or fixes to
-documentation, may be landed within the minimum 48 hour window.
-
-Abandoned or stalled pull requests
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If a pull request appears to be abandoned or stalled, it is polite to first
-check with the contributor to see if they intend to continue the work before
-checking if they would mind if you took it over (especially if it just has
-nits left). When doing so, it is courteous to give the original contributor
-credit for the work they started (either by preserving their name and email
-address) in the commit log, or by using an :code:`Author:` meta-data tag in the
-commit.
-
-Approving a change
-^^^^^^^^^^^^^^^^^^^
-
-Any GraphAr core collaborator (any GitHub user with commit rights in the
-:code:`apache/incubator-graphar` repository) is authorized to approve any
other contributor's
-work. Collaborators are not permitted to approve their own pull requests.
-
-Collaborators indicate that they have reviewed and approve of the changes in
-a pull request either by using GitHub's Approval Workflow, which is preferred,
-or by leaving an :code:`LGTM` ("Looks Good To Me") comment.
-
-When explicitly using the "Changes requested" component of the GitHub Approval
-Workflow, show empathy. That is, do not be rude or abrupt with your feedback
-and offer concrete suggestions for improvement, if possible. If you're not
-sure **how** a particular change can be improved, say so.
-
-Most importantly, after leaving such requests, it is courteous to make yourself
-available later to check whether your comments have been addressed.
-
-If you see that requested changes have been made, you can clear another
-collaborator's :code:`Changes requested` review.
-
-Change requests that are vague, dismissive, or unconstructive may also be
-dismissed if requests for greater clarification go unanswered within a
-reasonable period of time.
-
-Use :code:`Changes requested` to block a pull request from landing. When doing
so,
-explain why you believe the pull request should not land along with an
-explanation of what may be an acceptable alternative course, if any.
-
-Performance is not everything
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-GraphAr has always optimized for speed of execution. If a particular change
-can be shown to make some part of GraphAr faster, it's quite likely to be
-accepted.
-
-That said, performance is not the only factor to consider. GraphAr also
-optimizes in favor of not breaking existing code in the ecosystem, and not
-changing working functional code just for the sake of changing.
-
-If a particular pull request introduces a performance or functional
-regression, rather than simply rejecting the pull request, take the time to
-work *with* the contributor on improving the change. Offer feedback and
-advice on what would make the pull request acceptable, and do not assume that
-the contributor should already know how to do that. Be explicit in your
-feedback.
-
-Continuous integration testing
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-All pull requests that contain changes to code must be run through
-continuous integration (CI) testing at `Github Actions
<https://github.com/apache/incubator-graphar/actions>`_.
-
-The pull request change will trigger a CI testing run. Ideally, the code change
-will pass ("be green") on all platform configurations supported by GraphAr.
-This means that all tests pass and there are no linting errors. In reality,
-however, it is not uncommon for the CI infrastructure itself to fail on
specific
-platforms ("be red"). It is vital to visually inspect the results of all
failed ("red") tests
-to determine whether the failure was caused by the changes in the pull request.
-
-Format specification & Libraries implementation
------------------------------------------------
-
-The GraphAr includes the format specification and libraries implementation.
The libraries implementation is based on the format specification.
-When you request a new feature to the format specification, you should first
open a feature request issue and discuss with the community.
-If the feature is accepted, you can submit a pull request update the `format
specification design`_. After the format specification is updated,
-you can submit a pull request to the related libraries implementation to
implement the new feature and update the `implementation status`_.
-
-
-.. _pre-commit: https://pre-commit.com/
-
-.. _Code of Conduct:
https://github.com/apache/incubator-graphar/blob/main/CODE_OF_CONDUCT.md
-
-.. _file a bug issue:
https://github.com/apache/incubator-graphar/issues/new?assignees=&labels=Bug&template=bug_report.yml&title=%5BBug%5D%3A+%3Ctitle%3E
-
-.. _Open a feature request issue:
https://github.com/apache/incubator-graphar/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFeat%5D
-
-.. _fork GraphAr: https://help.github.com/articles/fork-a-repo
-
-.. _make a Pull Request:
https://help.github.com/articles/creating-a-pull-request
-
-.. _Github Discussions: https://github.com/apache/incubator-graphar/discussions
-
-.. _git rebasing: http://git-scm.com/book/en/Git-Branching-Rebasing
-
-.. _interactive rebase:
https://help.github.com/en/github/using-git/about-git-rebase
-
-.. _GraphAr C++ Dependencies:
https://github.com/apache/incubator-graphar/tree/main/cpp#system-setup
-
-.. _GraphAr Spark Dependencies:
https://github.com/apache/incubator-graphar/tree/main/spark#system-setup
-
-.. _Contributor License Agreement:
https://cla-assistant.io/apache/incubator-graphar
-
-.. _glossary:
https://chromium.googlesource.com/chromiumos/docs/+/HEAD/glossary.md
-
-.. _format specification design:
https://github.com/apache/incubator-graphar/tree/main/docs/format/file-format.rst
-
-.. _implementation status:
https://github.com/apache/incubator-graphar/tree/main/docs/format/status.rst
diff --git a/README.md b/README.md
index 2d71d13..8817096 100644
--- a/README.md
+++ b/README.md
@@ -14,11 +14,7 @@
Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://graphar
[](https://github.com/apache/incubator-graphar/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
-📢 Join our [Weekly Community
-Meeting](https://github.com/apache/incubator-graphar/wiki/GraphAr-Weekly-Community-Meeting)
-to learn more about GraphAr and get involved!
-
-# What is GraphAr?
+## What is GraphAr?
<img src="docs/images/overview.png" class="align-center" width="770"
alt="Overview" />
@@ -53,7 +49,7 @@ By using GraphAr, you can:
- Utilize Apache Spark to quickly manipulate and transform your GAR
files
-# The GAR File Format
+## The GAR File Format
The GAR file format is designed for storing property graphs. It uses
metadata to record all the necessary information of a graph, and
@@ -79,9 +75,9 @@ vertices ("person" and "comment") and three types of edges.
<img src="docs/images/property_graph.png" class="align-center"
width="700" alt="property graph" />
-## Vertices in GraphAr
+### Vertices in GraphAr
-### Logical table of vertices
+#### Logical table of vertices
Each type of vertices (with the same label) constructs a logical vertex
table, with each vertex assigned with a global index inside this type
@@ -98,7 +94,7 @@ destination vertices when maintaining the topology of the
graph.
<img src="docs/images/vertex_logical_table.png" class="align-center"
width="650" alt="vertex logical table" />
-### Physical table of vertices
+### Physical table of vertices
The logical vertex table will be partitioned into multiple continuous
vertex chunks for enhancing the reading/writing efficiency. To maintain
@@ -126,9 +122,9 @@ continuous, the payload file format can use the delta
encoding for the
internal vertex id column, which would not bring too much overhead for
the storage.
-## Edges in GraphAr
+### Edges in GraphAr
-### Logical table of edges
+#### Logical table of edges
For maintaining a type of edges (that with the same triplet of the
source label, edge label, and destination label), a logical edge table
@@ -147,7 +143,7 @@ the logical edge table looks like:
<img src="docs/images/edge_logical_table.png" class="align-center"
width="650" alt="edge logical table" />
-### Physical table of edges
+#### Physical table of edges
As same with the vertex table, the logical edge table is also
partitioned into some sub-logical-tables, with each sub-logical-table
@@ -198,20 +194,20 @@ width="650" alt="edge logical table1" />
<img src="docs/images/edge_physical_table2.png" class="align-center"
width="650" alt="edge logical table2" />
-# Building Libraries
+## Libraries
GraphAr offers a collection of libraries for the purpose of reading,
writing and transforming files. Currently, the following libraries are
available, and plans are in place to expand support to additional
programming language.
-## The C++ Library
+### The C++ Library
See [GraphAr C++
Library](https://github.com/apache/incubator-graphar/tree/main/cpp) for
details about the building of the C++ library.
-## The Java Library
+### The Java Library
The GraphAr Java library is created with bindings to the C++ library
(currently at version v0.10.0), utilizing
@@ -220,59 +216,35 @@ implementation. See [GraphAr Java
Library](https://github.com/apache/incubator-graphar/tree/main/java) for
details about the building of the Java library.
-## The Spark Library
+### The Spark Library
See [GraphAr Spark
Library](https://github.com/apache/incubator-graphar/tree/main/spark)
for details about the Spark library.
-## The PySpark Library
+### The PySpark Library
The GraphAr PySpark library is developed as bindings to the GraphAr
Spark library. See [GraphAr PySpark
Library](https://github.com/apache/incubator-graphar/tree/main/pyspark)
for details about the PySpark library.
-# Contributing
-
-## Contributing Guidelines
-
-Read through our [contribution
-guidelines](https://github.com/apache/incubator-graphar/tree/main/CONTRIBUTING.rst)
-to learn about our submission process, coding rules, and more.
-
-## Code of Conduct
-
-Help us keep GraphAr open and inclusive. Please read and follow our
-[Code of
-Conduct](https://github.com/apache/incubator-graphar/blob/main/CODE_OF_CONDUCT.md).
-
-# Getting Involved
-
-Join the conversation and help the community. Even if you do not plan to
-contribute to GraphAr itself or GraphAr integrations in other projects,
-we'd be happy to have you involved.
-
-- Ask questions on [GitHub
- Discussions](https://github.com/apache/incubator-graphar/discussions).
- We welcome all kinds of questions, from beginner to advanced!
-- Follow our activity and ask for feature requests on [GitHub
- Issues](https://github.com/apache/incubator-graphar/issues/new).
-- Join our [Weekly Community
-
Meeting](https://github.com/apache/incubator-graphar/wiki/GraphAr-Weekly-Community-Meeting).
+## Contributing
-Read through our [community
-introduction](https://graphar.apache.org/community/)
-to learn about our communication channels, governance, and more.
+- Start with [Contributing Guide]().
+- Submit [Issues]() for bug reports, feature requests.
+- Discuss at [dev mailing list](mailto:[email protected])
([subscribe](mailto:[email protected]?subject=(send%20this%20email%20to%20subscribe))
/
[unsubscribe](mailto:[email protected]?subject=(send%20this%20email%20to%20unsubscribe))
/ [archives](https://lists.apache.org/[email protected])).
+- Asking questions on [GitHub
Discussions](https://github.com/apache/graphar/discussions/new?category=q-a).
+- Join our [Weekly Community
Meeting](https://github.com/apache/incubator-graphar/wiki/GraphAr-Weekly-Community-Meeting).
-# License
+## License
**GraphAr** is distributed under [Apache License
2.0](https://github.com/apache/incubator-graphar/blob/main/LICENSE).
Please note that third-party libraries may not have the same license as
GraphAr.
-# Publication
+## Publication
- Xue Li, Weibin Zeng, Zhibin Wang, Diwen Zhu, Jingbo Xu, Wenyuan Yu,
Jingren Zhou. [Enhancing Data Lakes with GraphAr: Efficient Graph Data
diff --git a/cpp/README.md b/cpp/README.md
index 1905bf1..f03b948 100644
--- a/cpp/README.md
+++ b/cpp/README.md
@@ -56,17 +56,6 @@ Release build:
$ make -j8 # if you have 8 CPU cores, otherwise adjust, use
-j`nproc` for all cores
```
-Build the Apache Arrow dependency from source:
-
-By default, GraphAr try to find Apache Arrow in the system. This can be
configured to build Arrow dependency automatically from source:
-
-```bash
- $ mkdir build
- $ cd build
- $ cmake -DBUILD_ARROW_FROM_SOURCE=ON ..
- $ make -j8
-```
-
Debug build with unit tests:
```bash
@@ -78,24 +67,16 @@ Debug build with unit tests:
$ make test # to run the tests
```
-Build with examples:
+Build with examples, you should build the project with `BUILD_EXAMPLES`
option, then run:
```bash
- $ export GAR_TEST_DATA=$PWD/../testing/
- $ mkdir build-examples
- $ cd build-examples
- $ cmake -DBUILD_EXAMPLES=ON ..
$ make -j8 # if you have 8 CPU cores, otherwise adjust, use
-j`nproc` for all cores
$ ./bgl_example # run the BGL example
```
-Build with benchmarks:
+Build with benchmarks, you should build the project with `BUILD_BENCHMARKS`
option, then run:
```bash
- $ export GAR_TEST_DATA=$PWD/../testing/
- $ mkdir build-benchmarks
- $ cd build-benchmarks
- $ cmake -DBUILD_BENCHMARKS=ON ..
$ make -j8 # if you have 8 CPU cores, otherwise adjust, use
-j`nproc` for all cores
$ ./graph_info_benchmark # run the graph info benchmark
```
@@ -121,4 +102,3 @@ The API document is generated in the directory
``docs_doxygen``.
## How to use
Please refer to our [GraphAr C++ API
Reference](https://graphar.apache.org/docs/libraries/cpp).
-
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
