Starting contributing

A general introduction: What does it mean to be a Open Source Maintainer. A brief history of Semantic Web technologies and data processing.

  1. Read the blog posts from GSOC 2017: Lorenzo Chris Akshay
  2. What is a REST API; how is it different from an RPC API
  3. What is a graph and how it can be represented with linear algebra. Watch this video about Graph structures and this one about directed graphs
  4. General understanding of RDF: Wikipedia - Google Scholar: especially the concept of representing data in triples. (video reference)
  5. What are Linked Data (video reference)
  6. What is JSON-LD (video reference)
  7. Read these two papers Hydra: A Vocabulary for Hypermedia-Driven Web APIs (Markus Lanthaler, Christian Gütl (2013)) and Creating 3rd Generation Web APIs with Hydra (Markus Lanthaler (2013))
  8. Read the old HYDRA Draft and updated specifications. Very important is the current work done for Draft’s use-cases
  9. Read this seminal paper about Web APIs. This other paper explains different use cases for graphs applied to databases.
  10. Read Hydra-CG gitbook
  11. Read hydrus WIKI. Run hydrus and try to set up a basic API. Read the documentation
  12. If you want to have fun with a more dynamic demo, run hydra-flock-demo
  13. All the conversations take place on Organization’s Slack, check the appropriate #channel
  14. Read the other blogposts in our Medium Publication
  15. Get familiar with Docker container engine and its best practices to deploy virtualized environments.

General guidelines to contributing

About OpenSource and Github

  • Read this how-to about Github workflow here if you are not familiar with
  • Read all the texts related to contributing for an OS community
  • Read this how-to about writing a PR and this other how-to about writing a issue
  • In general, no permission is needed to work on the code. Fork develop branch and keep your downstream branch updated; when done submit a PR and ask for reviewing. PR is the natural place for code comparison and corrections. Code for issues with multiple PRs will be integrated at reviewing time.
  • If you are working on a new idea/core modification it’s important that it adhere to the HYDRA Draft. We don’t add anything to the API documentation that is not defined in the Hydra spec.

Asking for help

  • If you find a problem, first ask for help in the chat, then consider opening a issue.
  • Please check existing or closed issues or PRs when thinking about opening a new one.

Opening a Pull Request

  • Every PR should follow the PR template. PR template for hydrus can be found here.
  • Code in PRs should be accurately compliant with PEP-8, checking code with pylint is fine.
  • Every method in the PR should have a compelling docstring in the format: 
    def test_method(arg1, arg2, ...):
  """
  Description of what the method performs.

  Generic Notes to consider when running the method if any

 :param arg1: what kind of value is expected
 :param arg2: what kind of value is expected
 :return : what is returned or `None`
 """
  • Every module is and should in future provide type annotations using mypy
  • Before opening a PR be sure that all the tests pass successfully. If any is failing for non-related reasons, annotate the test failure in the PR comment.
  • Any change should be PRed first in develop, master can only receive merge from develop.
  • Everything should work and be tested for Python 3.6.0 and above.

Worth knowing

Design annotations

  • hydrus is developed in flask because the applications we had in mind were mostly related to IoT and sensors, so it was supposed to be lightweight and functional. By the way we can consider also more structured options like having versions that works with Django or Pyramid.
  • Read the issues labeled as “wiki”