-
Notifications
You must be signed in to change notification settings - Fork 0
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.
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
Initial content draft #1
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,65 @@ | ||
# readme-template | ||
# readme-template (Project's title goes here) | ||
|
||
## 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. | ||
|
||
 | ||
|
||
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 | ||
|
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What would we do with external contributions? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What badges would you add? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
# Project title | ||
|
||
## Description | ||
|
||
## Requirements | ||
|
||
## Installation | ||
|
||
## Usage | ||
|
||
## Contributing |
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="<font color="#000000">Section 1</font>" 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="<font color="#000000">Section 2</font>" 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="<font color="#000000">Section 3</font>" 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> |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.