cfpb / open-source-project-template Goto Github PK

The Technology Stack and Dependencies sections overlap each other and it's not clear what should be included in one versus the other. Are there examples in the existing code base?
It seems helpful to have the dependencies section list the software that is then installed in Installation section that immediate follows it.

Some readmes have them, some don't. Does the project template have an opinion?

echo "I'm a console command!"

$ echo "so am I!"

cfgov-refresh has the following URL in the readme that populates a new bug report with filled in values:

The URL looks like:
https://github.com/cfpb/cfgov-refresh/issues/new?body=%23%23%20URL%0D%0D%0D%23%23%20Actual%20Behavior%0D%0D%0D%23%23%20Expected%20Behavior%0D%0D%0D%23%23%20Steps%20to%20Reproduce%0D%0D%0D%23%23%20Screenshot&labels=bug

The new issue gets populated with a set label and content:

A generic template for a URL like this might be nice to include in this repo's example project Readme. It could be copied-and-pasted and with filler for the project... e.g.:

https://github.com/cfpb/<REPLACE WITH PROJECT REPOSITORY NAME>/issues/new?body=%23%23%20Actual%20Behavior%0D%0D%0D%23%23%20Expected%20Behavior%0D%0D%0D%23%23%20Steps%20to%20Reproduce%0D%0D%0D%23%23%20Screenshot&labels=bug

They kind of fit under Known Issues... but are also kind of separate. See e.g. [GHE]/CFPB/UnityBox#troubleshooting

Installation can be quite a long section, but only needs to be read once (ideally). Having it in the main readme hurts scan-ability and detracts from reading over usage and config instructions.

The instructions say an external file can be linked to, but perhaps this repo should set a precedence of having installation instructions in their own file like the contributing doc and changelog are?

I'd suggest:

• Move all installation instructions to INSTALL.md in the project root directory.
• Simply have the readme list this for installation instructions:

## Installation
Follow the instructions in [INSTALL](INSTALL.md).