Select Page

Developer FAQ: Working with GitHub

RESO GitHub Repository Organization

Overview

This document provides general guidelines and recommendations for the RESO GitHub repositories, its management, and use. Specifically, the intent is to provide a set of recommended code repository governance principles based on the industries best practices and observed GitHub related rules-of-thumb.

The RESO GitHub repositories can be found at: RESOStandards

Repository Naming

A proper repository name is the first key component for users to find the repository, either using the GitHub.com’s search functionality or using search engines, such as Google. The recommended format is a product/code keyword set, separated by hyphens (-):

<organization>-<service/product>-<code product>-<platform/programming language>-<supportstatus>

To complement the repository name component a short (1 sentence) GitHub description for the repository should also be provided. 

Examples of repository naming and descriptions:

  • RESO-WebAPI-Client-PHP: PHP library for the RESO Web API services.
  • RESO-WebAPI-Client-dotNet: .Net library for the RESO Web API services.
  • RESO-RETS-ClientTester-Java-Legacy: .Net testing platform for RETS Clients. No longer supported, hence ‘Legacy’

Content Structure

The following are the recommended standard content component set:

  • src/ | lib/ | <product-name>/ – the main product’s directory, where the source code (and dependencies, if required) should reside with its own internal directory and file structure, depending on the development platform/language needs, internal development guidelines and the application architecture. The aim is to store the main code in a dedicated directory, so distinguishing it from the rest of the supporting files and directories, which reside in the same repository;
  • docs/ – directory of all relevant code documentation, such as usage and installation guides, function manual and other;
  • tests/ – directory, where the unit, integration and/or other code tests should reside;
  • examples/ – directory, where a sample set of code implementation should be demonstrated. Best to cover every major angle of the code use, where applicable, e.g. like Command Line application (CLI) used, use in a web application and similar;
  • README.md – a Markdown language file describing all the main aspects of the repository. Requirements for the content and file template is provided in a separate section of this document;
  • CONTRIBUTING.md – a Markdown language file, which contains the guidelines for contributing to the repository hosted code. Defines the issue tracking and bug report principles, pull request handling and similar. A template file is provided in a separate section of this document;
  • ISSUE_TEMPLATE.md – a Markdown language file containing the guidelines on how to post an issue/bug report in the GitHub repository. Template content for the file is provided in the “Issue Reporting” section;
  • PULL_REQUEST_TEMPLATE.md – a Markdown language file, containing the guidelines for proper Pull Request description. The content of the template is provided in the “Pull Requests” section together with the handling procedure;
  • CHANGELOG.md – extensive development, improvements, changes to the code set might require a changelog file, which would contain the different code versions and main bullet points of changes introduced in each version. A template file is provided in a separate section of this document;
  • LICENSE.md – A file supplied by RESO that contains the all the code license details and terms. 

These are the standard expected repository content components, which are usually found commonly in other well developed GitHub repositories. Depending on the situation additional content structure is allowed to be stored if needed. The *.md files are also included in this zip file: RESO md files 2018-08-13.zip.

Standard Content Components

To meet the content structure recommendations some of the components should follow a particular template and content guidelines. The template might differ slightly from case to case and development platform. The most important content components are described here:

File – README.md

The README.md Markdown language file is an essential component of a GitHub repository, which contains the overview of the repository and essential information to the developers. GitHub renders the README.md file and inlines it in the repository view next to the file and directory tree. The README.md file stands as an overview/introduction page of the repository.  

The README.md file should cover the following topics (if applicable):

    • Title of the repository as a heading;
    • Short description about the repositories purpose and code content;
    • Information widgets/badges (recommended, but not mandatory), such as – build status (if CI tool is used), latest version badge, license, code coverage and others. Examples provided in the README.me template file;
    • Requirements of dependencies to run the code;
    • Installation guidelines;
    • Getting started guidelines and references to example applications;
    • Testing guidelines (if unit, integration and/or other types of code tests are used);
    • Specific code configuration, usage guidelines, which would be essential for successful and efficient code execution and use;
    • Any notes or warnings for the developers, depending on the situation and specific code set;
    • Any situation and/or language specific sections, which would be necessary to efficiently utilize the repository’s code set.

Please utilize this attached readme template: README_Template.md

File – CONTRIBUTING.md

The contribution file describes the guidelines for the external contributors if they want to submit their code proposals to be merged with the git repositories code base. A standardized process and procedure of contribution ensure an effective way of handling externally submitted changes, using a standardized way of describing the changes, issuing a pull request, testing the pull request using unit tests and reviewing/approving those by the code maintainers.

Please utilize this attached contributing template: CONTRIBUTING_Template.md

File – CHANGELOG.md

Code set changelog file, related to code releases, gives a good overview of the development of the code, potential breaking changes and addition of new functionality or issue fixes. It stands a journal of the code evolution and gives an easy overview of the past code modification activities.

The changelog should contain only the major additions, changes, fixes of a particular code release. However, depending on the situation and requirements the change log could contain the whole set of commits (commit log) for a particular release version.

Please utilize this attached changelog template: Changelog_Template.md

File – LICENSE

LICENSE file should be included in the code base’s parent directory and define the license terms for the use, distribution, modification of the code. It should be the RESO created license.

See License.md

Commits & Descriptions

To ensure easier code change management each commit should contain a single logical code change and not bundle several ones. This would allow to handle and revert need, specific version fork and change tracking much easier. For example, if a patch fixes an issue, but also adds new functionality – such commit should be split into two or several commits.

It is essential to write informative, but not too long, descriptions of each commit. The essence of the commit should fit into 72 characters or less. After the first line commit line further details can be provided, also such information as references to issue record and/or pull request.

Branches, Versioning & Releases

The general recommendation for the code branches in the GitHub repository would be as following:

  • master – the stable current version branch. This branch should only receive critical bug fixes and otherwise be updated on new version release, by merging against the develop branch;
  • develop – the main development, fixes, new functionality addition branch. 
    • The direct updates to the code should only be done by the maintainers or strictly by using the pull requests procedure. 
    • The develop branch is merged with the fixes/ and feature/ branches whenever suitable;
  • fixes/<fix-name> – branch naming for bug and issue fixes. Should be based on the develop branch and rebased when creating a pull request accordingly. 
    • After the pull request is accepted, the branch is merged into the develop branch. 
    • The name of the branch should specifically identify what kind of issue or bug is being fixed;
  • feature/<feature-name> – similarly like with the fixes/ branches, the feature/ branch would be created out of the develop branch to add new features and functionalities. 
    • Once finalized, the branch should be rebased according to latest develop branch and a pull request for merging created.

After the fixes/ and features/ branches are approved and merged with the develop branch, those should be deleted to maintain tidiness in the GitHub repository.

Once the develop branch is stable and a new version release is planned – the versioning files, such as CHANGELOG.md should be updated appropriately and the master should be merged with the current development branch version. The new version of the master branch should be nominated as a new release in the “Releases” section of the GitHub repository and any upstream package management services (if used) should be updated with the latest release.

Version numbering relies on the internal development principles and guidelines.

Issue Reporting

GitHub repositories provide an integrated tool to report issues. To establish a tidy an effective way of issue reporting, the issue should follow a set template (see below). 

See ISSUE_Template.md

Pull Requests

If the GitHub code repository is intended for public participation and contribution to the development, it is highly recommended that the updates to the code base would be carried out using the Pull Request procedure.

For RESO developers (e.g RESO Contractors, Author, Approved Contributors, etc), the procedure should follow the branching principles (see Branches, Versioning & Releases section above), where the “develop” branch is cloned into new branches depending on the purpose of the code change (issue/bug fix or new feature addition) and later on, when the work is finalized, a Pull Request should be created in the repository with a description of the change according to the proposed template in this section. The pull request should be reviewed by at least two RESO developers before being merged. Depending on the situation, when there a single developer is maintaining the code and repository, it is up to the developer to decide the review and merging principles, where pull requests would be not necessary as it would add unneeded overhead.

For public / non-RESO developers and contributors, the procedure is to fork the “develop” branch to a local repository, apply the proposed changes, create a finalized commit to the forked repository and carry on with the Pull Request procedure according to the proposed template in this section.

The RESO repository ‘maintainers’ review the description and the code changes and either approves, rejects or requests for further modifications. Also, in addition, if code testing procedures are used (e.g. unit testing), the pull request must contain appropriate tests or current test changes to ensure that the whole code set is still valid and functioning as expected after the change. Unit tests would show the potential issues if there were errors in programming the change and/or certain behavior after the code change was not identified or expected. Therefore, in addition to the maintainer review, the code testing should also be a measure to pass before approving the Pull Request merging with the develop branch.

The proposed template for the Pull Request description is below and will be located the parent repository directory

See PULL_REQUEST_Template.md

Note: A pull request might be opened for work-in-progress code changes, also utilizing the Continuous Integration (CI) tools that execute the unit tests against all the code base. If the Pull Request should not be yet reviewed and/or merged with the develop branch, a “do not merge” tag should be added to the Pull Request.

Language Specific Tools and Files

Depending on the programming language for which the code is being produced, it might be that somewhat different file and directory structure is required. In such case, the files and/or directories should be added and in case this would become a repeatable activity – this guidelines document should be appended with the new guidelines for the specific cases, so it would become a standard approach.

Tests & Continuous Integration

To ensure the integrity of the code set, hosted in the GitHub repository, especially if public contribution will be accepted, code testing mechanisms is a mandatory tool to ensure that the continuous integration principles would work properly. Therefore, it is highly advised that the code maintainers would introduce code tests (unit, integration, other tests – depending on the situation), where the code would be always covered with such tests.

This would allow to quickly evaluate any change to the code base – either directly or through a pull request – if the change does not break the whole code base and introduce additional issues.

The rule-of-thumb would be to cover a much of the code with code tests as possible, as this would ensure fast and accurate evaluation of the code integrity when changes to the code are applied.

GitHub provides integration with CI tools, which would take over automated test execution and validation. Such tools are – TravisCI, CircleCI. It is up to the developer to choose which tool to use in particular case. Other tools can be found at the GitHub Marketplace – https://github.com/marketplace/category/continuous-integration

Code Examples

The examples/folder should contain a viable set of usage examples, in a form of configuration files, executables, scripts, to demonstrate the use of the product.

Depending on what type of code is hosted, the examples/folder content and structure might differ from RESO repository to repository. The rule of thumb is to provide the content, which would be useful for users to easily prepare and execute the code (if it is a standalone application) or integrate it in the development process (if it is a module, library and/or SDK).

Some generalized principles:

  • Standalone applications should contain the required material (if any) to execute those. E.g. if the application accepts configuration files a different set of example configuration files should be provided to cover the main aspects of use and functionality;
  • Module / Library / SDK – provide a simple, but the main / core functionality covering demo application. If the code product implements several different application formats (desktop, Web, CLI and other), a demo application should be provided for each format. Likewise, if it implements different platforms and architectures, a demo application should be provided for each of those combinations or as much as possible and reasonable;
  • If the code product has special deployment and/or integration steps, which differ on the situation (e.g. different platform, use, architecture), the examples/folder could contain deployment guidelines, scripts, tools or anything that would fasten the installation/implementation process. E.g. build scripts for different platforms; supporting files if needed for integration in upstream products (e.g. plug-in of a particular system/framework).

The examples/ folder structure is left free format and for the maintainer/developer to decide. 

Please take into account that RESO will have developers at many different levels of expertise wanting to use its repositories.  We’re hoping the examples will address all of these levels.

Community & Discussions

GitHub repositories issue tracking tool and pull requests are kind of an environment for development discussions because it provides the functionality of commenting, reviewing the changes/commits, referencing issues and pull requests between each other and similar.

DLU October 5th, 2018 Back to top

GitHub Glossary

Below are a list of some Git and GitHub specific terms we use across our sites and documentation.

Blame

The “blame” feature in Git describes the last modification to each line of a file, which generally displays the revision, author and time. This is helpful, for example, in tracking down when a feature was added, or which commit led to a particular bug.

Branch

A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or master branch allowing you to work freely without disrupting the “live” version. When you’ve made the changes you want to make, you can merge your branch back into the master branch to publish your changes. For more information, see “About branches.”

Check

A check is a type of status check on GitHub. See “Status checks.”

Clone

A clone is a copy of a repository that lives on your computer instead of on a website’s server somewhere, or the act of making that copy. With your clone you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. It is, however, connected to the remote version so that changes can be synced between the two. You can push your local changes to the remote to keep them synced when you’re online.

Collaborator

A collaborator is a person with read and write access to a repository who has been invited to contributeby the repository owner.

Commit

A commit, or “revision”, is an individual change to a file (or set of files). It’s like when you save a file, except with Git, every time you save it creates a unique ID (a.k.a. the “SHA” or “hash”) that allows you to keep record of what changes were made when and by who. Commits usually contain a commit message which is a brief description of what changes were made.

Contributor

A contributor is someone who has contributed to a project by having a pull request merged but does not have collaborator access.

Dashboard

Your personal dashboard is the main hub of your activity on GitHub. From your personal dashboard, you can keep track of issues and pull requests you’re following or working on, navigate to your top repositories and team pages, and learn about recent activity in repositories you’re watching or participating in. You can also discover new repositories, which are recommended based on users you’re following and repositories you have starred. To only view activity for a specific organization, visit your organization’s dashboard. For more information, see “About your personal dashboard” or “About your organization dashboard.”

Diff

A diff is the difference in changes between two commits, or saved changes. The diff will visually describe what was added or removed from a file since its last commit.

Fetch

Fetching refers to getting the latest changes from an online repository without merging them in. Once these changes are fetched you can compare them to your local branches (the code residing on your local machine).

Fork

A fork is a personal copy of another user’s repository that lives on your account. Forks allow you to freely make changes to a project without affecting the original. Forks remain attached to the original, allowing you to submit a pull request to the original’s author to update with your changes. You can also keep your fork up to date by pulling in updates from the original.

Git

Git is an open source program for tracking changes in text files, and is the core technology that GitHub, the social and user interface, is built on top of.

Issue

Issues are suggested improvements, tasks or questions related to the repository. Issues can be created by anyone (for public repositories), and are moderated by repository collaborators. Each issue contains its own discussion forum, can be labeled and assigned to a user.

Markdown

Markdown is a simple semantic file format, not too dissimilar from .doc, .rtf and .txt. Markdown makes it easy for even those without a web-publishing background to write prose (including with links, lists, bullets, etc.) and have it displayed like a website. GitHub supports Markdown, and you can learn about the semantics.

Merge

Merging takes the changes from one branch (in the same repository or from a fork), and applies them into another. This often happens as a pull request (which can be thought of as a request to merge), or via the command line. A merge can be done automatically via a pull request via the GitHub web interface if there are no conflicting changes, or can always be done via the command line. For more information, see “Merging a pull request.”

Open source

Open source software is software that can be freely used, modified, and shared (in both modified and unmodified form) by anyone. Today the concept of “open source” is often extended beyond software, to represent a philosophy of collaboration in which working materials are made available online for anyone to fork, modify, discuss, and contribute to.

For more information on open source, specifically how to create and grow an open source project, we’ve created Open Source Guides that will help you foster a healthy open source community. You can also take a free GitHub Learning Lab course on maintaining open source communities.

Organizations

Organizations are shared accounts where businesses and open-source projects can collaborate across many projects at once. Owners and administrators can manage member access to the organization’s data and projects with sophisticated security and administrative features.

Private repository

Private repositories are repositories that can only be viewed or contributed to by their creator and collaborators the creator specified.

Pull

Pull refers to when you are fetching in changes and merging them. For instance, if someone has edited the remote file you’re both working on, you’ll want to pull in those changes to your local copy so that it’s up to date.

Pull request

Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository’s collaborators. Like issues, pull requests each have their own discussion forum. For more information, see “About pull requests.”

Push

Pushing refers to sending your committed changes to a remote repository, such as a repository hosted on GitHub. For instance, if you change something locally, you’d want to then push those changes so that others may access them.

Remote

This is the version of something that is hosted on a server, most likely GitHub. It can be connected to local clones so that changes can be synced.

Repository

A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private.

SSH key

SSH keys are a way to identify yourself to an online server, using an encrypted message. It’s as if your computer has its own unique password to another service. GitHub uses SSH keys to securely transfer information to your computer.

Status

A status is a type of status check on GitHub. See “Status checks.”

Status checks

Status checks are external processes, such as continuous integration builds, which run for each commit you make in a repository. For more information, see “About status checks.”

Team

Teams are groups of organization members that reflect your company or group’s structure with cascading access permissions and mentions.

Upstream

When talking about a branch or a fork, the primary branch on the original repository is often referred to as the “upstream”, since that is the main place that other changes will come in from. The branch/fork you are working on is then called the “downstream”.

User

Users are personal GitHub accounts. Each user has a personal profile, and can own multiple repositories, public or private. They can create or be invited to join organizations or collaborate on another user’s repository.

DLU October 17th, 2018 Back to top

What is GitHub?

GitHub Inc. is a web-based hosting service for version control using Git. It is mostly used for computer code. It offers all of the distributed version control and source code management (SCM) functionality of Git as well as adding its own features. It provides access control and several collaboration features such as bug tracking and feature requests.

DLU August 3rd, 2018 Back to top