Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initial content draft #1

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Initial content draft #1

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bf45b4e
WIP Initial content draft
lagoan Aug 24, 2022
14bd4f2
Update README.md
lagoan Oct 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 65 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,65 @@
# readme-template
# readme-teplace (Project's title goes here)
lagoan marked this conversation as resolved.
Show resolved Hide resolved

## Description

The goal of this template is to have a common starting point for the application support team's projects README.md documentation.

This README.md file is intended to be used as an example of how to approach the README.md file for your project.

A project diagram can help the reader grasp concepts of your project at a glance.

![Template diagram](./files/template.svg)

https://medium.com/the-internal-startup/how-to-draw-useful-technical-architecture-diagrams-2d20c9fda90d

http://draw.io
https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio

You can find a list of curated README.md files [here](https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/)

## Requirements
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I asked @kgood about some things he needs to know as a service manager. End of life dates for dependencies was something he wanted to know to give some context to maintenance work that might be needed and when. I'm not sure how we show this information.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding maintenance, I like how it is called out in the "2023 Library Application Development Projects" Google Doc. I'm unsure how much effort is required to keep each README updated with end-of-life dates.


In this section we can list any requirements that need to be met by the project, such as application software versions, required libraries or frameworks, optional services, etc. The requirements can be presented in list form to be easier to identify.

- Text editor
- Browser to check code (optional)
- git client to pull template repository (optional)

## Installation

Installing this README.md template can be done by getting the document in any fashion, such as pulling from the main repository and copying the README_TEMPLATE.md file over to your project's README.md file.

A simple way of getting the template is

## Usage

After copying the template over to your project you can simply start typing!

## Contributing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would we do with external contributions?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would the contributing be common across repositories? If so, would putting the details in a separate file, CONTRIBUTING.md like described here https://stackoverflow.com/a/72929094 save some time?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DMP main codebase has a Contribution Guide that DMP Assisant is using, (https://github.com/portagenetwork/roadmap/blob/integration/.github/CONTRIBUTING.md). We can refer to it if we want


If you would like to contribute to this project please follow these steps:

1. Make a comment on a github issue you would like to work on or create one if there isn't one.
2. Create a new branch from the main branch with a name that describes what the purpose of the branch might be.
3. Add your changes to branch and push to origin when you are ready to share your work.
4. Create a pull request from that branch. Don't forget to request someone a code review!
5. After resolving any issues that might come up with the code review and your changes are approved you can merge the changes in your branch.

## Sections

This README.md template is not meant to be a "one size fits all" solution, but rather, a good starting point to which we can add different sections where the need arises.

## Assumptions

## Definitions

## Badges
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What badges would you add?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DMP Assisant is using badges in README.md (https://raw.githubusercontent.com/portagenetwork/roadmap/deployment-portage/README.md). I think it really depends on the GitHub Actions for each project. No common standard for this.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://shields.io/ is a good place to make badges


Badges can give a quick overview of the state of the repository, be sure to add the badges from github actions XXX, or add more from the ones available from https://shields.io/.

You should add the badges on top of the description of the project to give the reader a read of the project at a glance.

## References

https://github.com/matiassingers/awesome-readme

11 changes: 11 additions & 0 deletions README_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Project title

## Description

## Requirements

## Installation

## Usage

## Contributing
19 changes: 19 additions & 0 deletions files/template.drawio
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<mxfile host="65bd71144e">
<diagram id="aK2l1F7p3P34JJqAnXL_" name="Page-1">
<mxGraphModel dx="358" dy="463" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="2" value="&lt;font color=&quot;#000000&quot;&gt;Section 1&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="40" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="3" value="&lt;font color=&quot;#000000&quot;&gt;Section 2&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="40" y="120" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="4" value="&lt;font color=&quot;#000000&quot;&gt;Section 3&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="40" y="200" width="120" height="60" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
1 change: 1 addition & 0 deletions files/template.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.