This is a template based on the standards of the IDB Digital Tools Publication Guide. We know that there is no single standard for supporting documentation and use of digital tools, but we have compiled these important characteristics that a readme.md should have to facilitate their use and amplify their potential impact. Any comment or recommendation, yo can create an issue or write to us directly at [email protected].
- This digital tool is part of the catalog of tools of the ** Inter-American Development Bank **. You can learn more about the IDB initiative at [code.iadb.org] (https://code.iadb.org) *
Logo and image or gif of the main interface of the tool
- Badges or shields
- Description and context
- User's Guide
- Installation guide
- How to contribute
- Code of conduct
- Author/s
- Additional Information
- License
- Limitation of responsibilities
It is common in many open source repositories to use badges or shields to give visibility to the use of microservices, licenses, downloads, etc. We recommend reviewing the https://shields.io/ initiative where, as you deem necessary, you can generate badges for your repo.
- code coverage percentage:
- stable release version:
- package manager release:
- status of third-party dependencies:
- static code analysis grade:
- SemVer version observance:
- amount of Liberapay donations per week:
- Python package downloads:
- Chrome Web Store extension rating:
- Uptime Robot percentage:
In the Code for Development initiative, we ask the teams that add their tools to the catalog to add the badge generated by the use of the SonarCloud static code evaluation microservice.
The badge looks like this and redirects to the static evaluation report of the last commit of the tool:
[! [Quality Gate Status] (https://sonarcloud.io/api/project_badges/measure?project=EL-BID_guia-de-publicacion&metric=alert_status)] (https://sonarcloud.io/dashboard?id=EL- BID_ publication-guide)
This is a README file. It must contain the supporting documentation for the use of the digital tool. The following sections are the recommended sections that you should include in any digital tool. You can download this file to serve as a template.
Be sure to start this file with a brief description of the functionalities and context of the digital tool. Be concise and to the point.
Explains the basic steps on how to use the digital tool. It is a good section to show screenshots or gifs to help you understand the digital tool.
Step by step of how to install the digital tool. In this section it is recommended to explain the architecture of folders and modules that make up the system.
Depending on the type of digital tool, the level of complexity may vary. On some occasions it may be necessary to install components that are dependent on the digital tool. If this is the case, add the following section as well. The installation guide should specifically contain:
- The operating system requirements for the compilation (specific versions of libraries, package and dependency management software, SDKs and compilers, etc.).
- The project's own dependencies, both external and internal (order of compilation of sub-modules, configuration of the location of dynamic libraries, etc.).
- Specific steps for compiling the source code and executing unit tests if the project has them.
Description of the external resources that generate a dependency for the reuse of the digital tool (libraries, frameworks, access to databases and licenses for each resource). It is good practice to describe the latest versions that the digital tool has been tested on.
You can use this font style to differentiate the installation commands.
This section explains to developers the common ways to submit a pull requests, how to declare bugs in the tool, and what style guides to use when writing more lines of code. You can also make a list of points that can be improved in your code to create ideas for improvement.
The code of conduct establishes the social norms, rules and responsibilities that individuals and organizations must follow when interacting in any way with the digital tool or their community. It is good practice to create an environment of respect and inclusion in contributions to the project.
The Github platform rewards and helps repositories have this file. When creating CODE_OF_CONDUCT.md you can start from a template suggested by them. You can read more about how to create a Code of Conduct file (here) [https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/]
Name the original author / s. Check with them before posting an email or personal name. A very common way is to direct them to your social media accounts.
This is the section that allows you to add more contextual information to the project such as a relevant website, similar projects or that have used the same technology.
The license specifies the permissions and conditions of use that the developer grants to other developers who use and / or modify the digital tool.
Include in this section a note with the type of license granted to this digital tool. The license text must be included in a * LICENSE.md * or * LICENSE.txt * file at the root of the repository.
If you do not know what types of licenses exist and which is the best for each case, we recommend you visit the page https://choosealicense.com/.
If the tool you are publishing with the Code for Development initiative has been financed by the IDB, we invite you to review the [bank's official license to publish software] (https://github.com/EL-BID/Plantilla-de-repositorio/blob/master/LICENSE.md)
Disclaimer: This section is only for IDB-funded tools.
The IDB will not be responsible, under any circumstance, for damage or compensation, moral or patrimonial; direct or indirect; accessory or special; or by way of consequence, foreseen or unforeseen, that could arise:
i. Under any theory of liability, whether by contract, infringement of intellectual property rights, negligence or under any other theory; me
ii. As a result of the use of the Digital Tool, including, but not limited to, potential defects in the Digital Tool, or the loss or inaccuracy of data of any kind. The foregoing includes expenses or damages associated with communication failures and / or computer malfunctions, related to the use of the Digital Tool.