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).
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
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
![certification%20central%20button_11.05.2015[1]](https://reso.org/wp-content/uploads/2016/02/certification20central20button_11.05.20151-300x239.jpg)