Initial content draft #1
Conversation
This work represents ideas of what our README.md template can look like. There is a lot of work still left to be done to be considered done but it can be a working start.
lagoan
requested review from
ConnorSheremeta,
jefferya,
nmacgreg,
pengyin-shan and
pgwillia
There was a problem hiding this comment.
I think this covers everything I would want to see in a software project repository.
I'm not sure what your workflow is for drawio/svg. I use this VS Code plugin. I also use the file extension drawio.svg because from the readme of that plugin:
.drawio.svg are valid .svg files that can be embedded in Github readme files! No export needed.
| You can find a list of curated README.md files [here](https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/) | ||
|
|
||
| ## Requirements |
There was a problem hiding this comment.
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.
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.
| After copying the template over to your project you can simply start typing! | ||
|
|
||
| ## Contributing |
There was a problem hiding this comment.
What would we do with external contributions?
There was a problem hiding this comment.
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.
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
| ## Definitions | ||
|
|
||
| ## Badges |
There was a problem hiding this comment.
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.
https://shields.io/ is a good place to make badges
Co-authored-by: Tricia Jenkins <[email protected]>
|
In my opinion, the work strikes a nice balance between being too prescriptive yet offering guidance toward what information is useful. I've tried out the template on another project (not with the Library) and it worked well however I chose not to use the sections: badges (I don't understand them well enough but could learn) and contribution (I don't expect external contributions). |
|
(Optional) If it is a long README.md, we can add a table of content at the beginning of the file, such as: |
This work represents ideas of what our README.md template can look like.
We can continue the discussions here if this looks like a good place to start.