search

ITDP / the-online-brt-planning-guide

Online collaborative version of the BRT Planning Guide
https://brtguide.itdp.org
Other
6 stars 20 forks source link

Move config hidden files to a directory #96

Closed aszasz closed 7 years ago

aszasz commented 7 years ago

I am back to work on Tutorial for Contributions... and I thougth it would be a good idea to reduce the number of files on the landing page of GitHub (<> Code) in order to allow README.md to be seen at arrival (without need to scroll down). The config hidden files add up to a good number already, so I was wondering if they could all go in a directory of their own. It may be a cheap trick, conceptually dubious (the conceptually right solution would be GitHub adding the tab for landing with README and LICENSE there... and maybe join Pulse and Graphs together... I will suggest that on the proper place), but very effective in getting an entry point of potential contributors that never seen GitHub before.

jonasmalacofilho commented 7 years ago

I wanted to organize those files too, but I was thinking in a purely hierarchical way...

Either way, as far as I know only two (pre-commit and enforce-lfs) or maybe three (Dockerfile) files can me moved somewhere other than the root... This is due to most tools thinking of the root as a special place: git, travis and robrt all do that to avoid the need for separate configs outside the repository telling where the actual config lives (and all these tools need the configs to be versioned).

aszasz commented 7 years ago

The license could be moved too... 3 files would make enough room (at least when seen in my current screen). A resonable alternative is to change the text on top (the short description about the project to be "roll down the page to see README file". Let this issue hang for a while, when the welcoming material is done, we come back to it.

jonasmalacofilho commented 7 years ago

Actually I don't think the license and copyright info can be moved : / They are supposed to be in the most obvious place possible, and GitHub even detects it in some cases.

On another note, I don't think we're on the right path when we discuss messing up the project description (it also appears in search results and repos one contributes to) or file hierarchy for solving the underlying issue here: being more welcoming for first time GitHub users.

Maybe we could address the issue in the Meta/Manual chapter, in the guide itself? Or maybe by adding a Wiki to the repository (although I'm not too fond of that idea, because it's versioned separately and gets out of sync with the project).

To be honest, I'm not sure the Readme should focus so much on the newcomer to GitHub: in my opinion, it should explain important things (that need to be communicated and kept up to date) to new and existing contributors to the project - like what it is, the file structure we use, how the system works, how to build&debug, who to contact when things go awry, etc. - but link/delegate some of "hey, this is a website called GitHub... and this is a git repo" to that more detailed guide chapter or other sources.

jonasmalacofilho commented 7 years ago

Either way, I'll look into what config files (specifically the dotfiles) can be moved someplace else.

This would still improve things, specially since we might need to add a couple more of those files sometime soon.

jonasmalacofilho commented 7 years ago

Files that can be moved off the project root:

Other files currently in the root: