Skip to content

Latest commit

 

History

History
110 lines (90 loc) · 9.95 KB

readme.md

File metadata and controls

110 lines (90 loc) · 9.95 KB
Raw

Contribution Guidelines

Welcome to the contribution guidelines for the KGC's Open Curriculum on Knowledge Graphs! We're happy to have you; take a look down below for an overview of

  • a guide of the mechanics of contributing,
  • what goes into contributing new content or to existing content, and
  • what sort of contributions we're looking for.

The Mechanics of Contributing

Technical Requirements for Contributing

It will first help to get an idea of how contributing will work. GitHub allows us to manage something called a git repository, which allows us to track changes made to the contents of the repository. It is fair to think of it as a sort of "slowed down Google Docs." Essentially, changes are gatekept by a set of maintainers. Changes by the community are driven via discussion in Issues, discussions in the Slack workspace, and by making Pull Requests via the GitHub interface. In the following guide, we'll give a short tutorial on how to do this, if you're unfamiliar with git and GitHub. If you are already comfortable with this process, please skip to the end where we describe the "Contribution Process" and the corresponding expectations.

The Process in a Nutshell

  1. "Fork" the Curriculum. That means you're going to create a local copy of the curriculum that is free for you to edit.
  2. Edit the Curriculum in place.
  3. Make a Pull Request, that will allow us to incorporate your changes into the Curriculum, pending discussion and review!
  4. Discuss the Pull Request with the community and maintainers, as necessary!

How do I "Fork" the repository?

  • First ,click on the Fork Button. Fork Button
  • Choose your username from the list (this may not pop up if you don't have multiple profiles).
  • This should put the local copy (the fork) into your own profile that you can freely edit!
  • See Also: Forking a Repository -- GitHub Docs

How do I edit the Curriculum?

  • First, navigate to the file that you wish to edit.
  • Click on the Edit Button (the pencil button) to edit the particular file. Edit File Button
  • When you're done editing, at the bottom of the file, fill in a short description of the changes that you made. There is also space for an extended description.
  • See Also: Editing Files -- GitHub Docs

How do I make a "Pull Request"?

  • First, navigate to the Pull Request Panel
  • Then, click on the "New pull request button". Pull Request Screen
  • If GitHub indicates that the changes can be merged, go ahead and click on the "Create pull request" button. Submit Pull Request
  • This will bring you to a page to title and describe your changes made in this Pull Request. Try to be descriptive! If you're addressing an issue from the parent repository, put that Issue's number in your description, like "Addresses Issue #123". This will help the maintainers review the changes to be accepted! You can also leave the right panel blank; the maintainers will fill this out!
  • There are guidelines below for more specific sort of information that should be included with pull requests and issues. Final Pull Request Step
  • See Also: Creating a Pull Request -- GitHub Docs

How do I file an Issue?

  • First, navigate to the Issues Panel of the Curriculum and click on the "New issue" button. New Issue
  • Include a description of the nature of the issue; try to be as thorough as possible.
  • There are guidelines below for the sort of information that should be included in an issue or pull request.
  • Add labels as appropriate.
  • No Trolling; be polite!
  • See Also: Creating an Issue -- GitHub Docs

A Guide for Contributing to Content

The first step to contributing is always to take a look at the open issues page. New contributions can also be discussed on the Slack Workspace! Also, keep in mind that contributions can, and often do, start quite small. As such, feel free to create a more open-ended issue and see where the discussion takes the feature-request.

For example, we could start with the question, "What does a Project Manager need to know about Tiger Graph?" At the time of this writing, we'd need a Project Manager audience created, a Module describing Tiger Graph, and a list of Concepts that are useful to know about a triplestore platform. Some might be new (e.g., "What is the cloud?") or might already be in our Curriculum (e.g., "Entailment Regimes").

The first two steps are always the same:

  1. First, check the open issues and pull requests for related ideas! We don't want to duplicate our work :)
  2. If there isn't, open a new Issue! The following headings below will describe what the differences are between the different conceptual items, and the sort of information that will help us create or modify them!

How do I contribute a new Learning Path?

This section is for if you believe that the currently supported learning paths are not sufficient for your needs. You can either create an issue and have a discussion around the topic (see "How do I file an Issue? or create a pull request. The following steps are for the latter and assume that you are operating out of your own fork of the curriculum.

  1. Every Learning Path has an top-level entry in the learning_paths.md file. Add your new Learning Path's name to the list, here.
  2. Each Learning Path has a customized description in learning_paths directory. Create a new Markdown file titled with the name of the learning path. Createa a File

Don't forget to include the .md after the title name! Create a Markdown File

  1. A tutorial for the Markdown syntax can be found here! It's quite simple :)
  2. There are two key pieces to the Learning Path. First, we need an "Objectives" section, which describes the overarching learning goals. The first four learning paths, for example, are "Academic", "Customer", "Implementer", and "Practitioner". Academics, for example are likely to want to dig into the theoretical foundations of Knowledge Engineering and Knowledge Graphs. Likely, many of the modules important to them, are not so important to the Customer!
  3. Next, we need a sequence of Modules in the "Module Sequence section." For example, a Practioner might start with "Introduction to Knowledge Engineering" and progress to "Deploying a Knowledge Graph", whereas a Customer might focus largely on modules from the Resources and Technology categories.
  4. These are the two key pieces! Submit your pull request and discuss your proposed changes!

How do I contribute to an existing Learning Path?

  1. You can either create an issue with your concerns or you can create a pull request with proposed changes.

How do I contribute new a Module?

This section is for if you think that there is a gap in our curriculum. You can either create an issue and have a discussion on your idea (e.g., perhaps a set of modules covers the gap?) or create a pull request that adds your proposed module to the curriculum. The following steps are for the latter and assume that you are operating out of your own fork of the curriculum.

  1. First, every Module has an entry in the modules.md file. Add the entry (using the details in Step 5) at the bottom of the file.
  2. If you are familiar with Python and have the appropriate environment, the create-template-module.py script will create a template of the module for you, requiring only your customization.
  3. A Module consists of several pieces.
    1. Title: Name your Module
    2. Fill out the details
      1. Category -- Which category or categories does this module fall into?
      2. Module Prerequisites -- Which modules from the curriculum are needed in order to understand the material in this module?
      3. Audience -- Who is the intended audience of this module?
      4. Level -- What level of expertise is expected to be able to understand and apply the material in this module?
      5. Covered Concepts -- What top level concepts are covered in this module?
    3. Content -- the article, tutorial, or content of the module. For example, please see the RDF article.
    4. Related KGC Media -- Are there existing workshops, tutorials, keynote talks, clubs, seminars, etc. that are related to this module? If so, link them here.
    5. References -- Include any references used in your Content section.
    6. Contributors -- Note who you are!
  4. That's it! Create the pull request and join the discussion for the review of your proposal!

How do I contribute to an existing Module?

  1. You can either create an issue with your concerns or you can create a pull request with proposed changes.

Pardon our mess ;)

Concepts and their implementation are currently under revision.

How do I contribute a new Concept?

  1. detail
  2. detail

How do I contribute to an existing Concept?

  1. You can either create an issue with your concerns or you can create a pull request with proposed changes.