1 of 39

Joining the OCDS Community on GitHub

2 of 39

Introduction

3 of 39

Introduction: Welcome

Welcome everyone

Introduce yourselves via Zoom chat
Notes will be provided in the notes doc (link)

Use this to ask questions which we can answer later
Any unanswered questions we’ll aim to send out via the mailing list

4 of 39

Introduction: Aims and Objectives

Aim: Inform community members how they may participate in OCDS development via Github

Introduce the ways in which OCDS standard development occurs through Github
Demonstrate how to find relevant OCDS discussions on Github
Demonstrate how to contribute to or create new OCDS discussions on Github

5 of 39

Introduction: Agenda

Target Length: 1 hour

How we use Github for OCDS

Some basic Git and Github vocabulary

Getting started with Github
Collaborating using Github

Finding issues and discussions
Creating issues
Community Discussions vs Implementation Support
OCDS tools on Github

Q&A and further resources

6 of 39

How we use Github for OCDS

7 of 39

OCDS Components

Schema

Documentation

Governance

+

Technical schema documentation

Implementation guidance

https://standard.open-contracting.org/latest/en/support/governance/

8 of 39

OCDS on Github

Technical:

Collaborative development
Issue tracking
Releases
Version control and change history

Social:

Discussions
Issue and Proposal reporting
Peer review

There are two main ways that we use Github, although these are not separated but interrelated.

Technical

Github allows multiple people to collaborate on technical development in one place. Multiple people can contribute code and improvements to the standard.
It allows us to track “issues” to fix bugs, develop new features, etc. these are often reported by a mixture of the OCP Team, the OCDS Helpdesk, and the community
Git is ultimately a version control system so it allows us to define and release different versions of the standard. Doing this also allows us to track the change history
Those familiar with the OCDS schema might recognise “change history” as something within OCDS. Although achieved differently the concept is roughly the same.

Social

Github also provides a space to engage in discussions around the data standard.
This is achieved through the creation and attendance of “issues”; discussion threads or bug reports on the standard.
The community are actively encouraged to engage in existing issues and submit new ones where appropriate (which we’ll go through eventually).
When a new version of OCDS is released the community may peer-review it on github

This shows the cyclical relationship between the two main ways OCDS is used on Github. Discussions and issue reporting feed into the collaborative development which results in versioning, which results in peer review, which results in an update to the standard and guidance. This in turn creates a new cycle. Now let’s see this in practice!

9 of 39

OCDS on Github: in Practice

The OCDS Standard Documentation contains a changelog showing the changes between versions of the standard

Changelog — Open Contracting Data Standard 1.1.5 documentation

The way these changes occur is through collaboration on Github

10 of 39

(Very) Basic Github Vocabulary

11 of 39

OCDS on Github: Key Vocabulary

Git is software used for version control. Github is a popular website for collaborating on projects using Git.

Key terms:

A Repository (Repo) is like a project or folder that everyone is working in. It contains the files that are changed.
An Issue is a discussion or thread that has been started on a repository. It may be used to report a bug, or start a larger discussion.
A Pull Request (PR) is a request to have some changes accepted to the repository.

12 of 39

OCDS on Github: Key Vocabulary

You can learn more about Git and Github using the following resources:

13 of 39

Main types of engagement

14 of 39

OCDS on Github: Reporting Problems

People often use issues to report problems with the OCDS Schema, codelists, and documentation.��The problem can be discussed and resolved in the issue thread and a change may be made to address this.

Examples: #798, #866, #918

15 of 39

OCDS on Github: Suggestions

Issues may be used to suggest new fields, codes, or documentation. This includes discussions on modelling procurement concepts in OCDS.��The design and implications of the fields, codes, and documentation is coordinated in the issue and the suggestion may be accepted for a future version of OCDS.

Examples: #395, #440, #764, #883, #1031

16 of 39

OCDS on Github: Feedback and Peer Review

When we release a draft release of OCDS we invite peer review on it.��Peer review gives a chance for the community to see the next version of the standard and ask questions, catch errors, and suggest small changes before release.

Examples: #429, #521, #966

17 of 39

Community Collaboration on Github

18 of 39

Getting started

19 of 39

OCDS on Github: Getting Started

To create and join discussions on Github you’ll need a Github Account.

Creating an account is free and simple: github.com/join

20 of 39

OCDS on Github: Getting Started

Practical Tips:

Adjust your notification settings to only get updates about what you’re interested in
Find our organization by heading to github.com/open-contracting
Issues about the OCDS Standard should be raised in the standard repository
Issues about extensions in the Extensions Explorer should be raised in the OCDS Extensions Repository

21 of 39

OCDS on Github: Getting Started

Useful quick links to popular repositories:

The OCDS Standard (/standard)
OCDS Extensions (/ocds-extensions)
Data Review Tool (/cove-ocds)

22 of 39

Finding and contributing to discussions

23 of 39

OCDS on Github: Finding Issues

Finding a discussion or issue on the OCDS Github is straightforward:

Locate the standard or the extensions repository
Navigate to the “issues” tab
Search for the topic using key terms and labels

Let’s demonstrate:

“Q: I would like to suggest a new field to disclose the members of the award committee”

24 of 39

OCDS on Github: Watching and Replying to discussions

You may watch or subscribe to an Issue by clicking the Subscribe button on the issue. You can unsubscribe any time.

You can add to the Issue by commenting using either the web interface or by replying to the email notification

25 of 39

OCDS on Github: Finding Issues

Practical Tips:

Narrow your search by using a label
You can search closed and historic issues by removing “is:open” from the search terms
Search multiple times using synonyms to cover the bases and get a variety of issues
Read discussions in linked issues when relevant to you
Watch an issue via the subscribe button to keep informed of updates
If in doubt contact the helpdesk using data@open-contracting.org

26 of 39

How to create new issues

27 of 39

OCDS on Github: Creating Issues

Creating a new issue is also straightforward. However you should always check existing issues first.

Let’s demonstrate:

“In [my country] procurements are bundled as a package but are not lots. They share a package number but have multiple buyers”

28 of 39

OCDS on Github: Creating Issues

Practical tips:

Always check for existing issues (both open and closed)
Use a very clear title for the issue
Describe use-case, bug, or model clearly in the issue body
Apply labels where possible
If in doubt, check with helpdesk before opening the issue data@open-contracting.org

29 of 39

Helpdesk or Github?

30 of 39

OCDS on Github: Helpdesk or Github?

Contact Helpdesk:

If you need help using the standard
If you need support with your implementation
If you’re not sure whether you should open a Github issue contact the Helpdesk at data@open-contracting.org

Open a Github issue:

If you’ve found a bug or problem with the standard, documentation, or tools
If you want to start a discussion about a new field, use-case, or procurement concept

31 of 39

OCDS on Github: Helpdesk or Github?

I need to know how to use a particular field in my OCDS publication

A: Contact Helpdesk <data@open-contracting.org>

32 of 39

OCDS on Github: Helpdesk or Github?

I think OCDS should include a new field for government branches

A: Open a Github Issue (#1027)

33 of 39

Collaborating on OCDS Tools

34 of 39

OCDS on Github: OCDS Tools?

Tools such as the OCDS Data Review Tool, Kingfisher, and OCDSKit are also managed openly and collaboratively via Github.

Each tool has a repository in which you can open issues to provide feedback, suggest changes, or report bugs

35 of 39

OCDS on Github: OCDS Tools?

Quick Links to OCDS Tool repositories:

Data Review Tool (/cove-ocds)
OCDSKit (/ocdskit) and OCDS Toucan (/toucan)
Kingfisher

Flatten Tool* (/OpenDataServices/flatten-tool)

* Flatten Tool is maintained by Open Data Services Co-operative

36 of 39

Bringing it together

37 of 39

OCDS on Github: Bringing it together

Let’s revisit the Changelog in light of what we now know:

Changes to OCDS are the result of collaboration via Github
Collaboration takes the form of discussions and reports via issues
The OCDS changelog links each change to the discussion which led to it

38 of 39

Closeout + Q&A

39 of 39

OCDS on Github: Bringing it together

We’ll answer some questions from the notes document now and also send out answers to all questions via the OCDS Standard Mailing list.

Join the mailing list: link
Contact the Helpdesk <data@open-contracting.org>