WIP: Remove .gitkeep files and mention self-explanatory alternative

[katrinleinweber]

Hi! Please see https://github.com/carpentries/lesson-example/issues/234 for background on this suggestion. Cheers :-)

[steve855]

I took a look at your changes and I think you have proposed an interesting idea. Making a README.md file does have a lot of advantages over the .gitkeep and I may start doing this myself. However, I don't think this is a good idea to incorporate into the lesson since lots of people still use .gitkeep files to keep empty folders under version control and if this line is removed from the lesson, the learners may not know what they are seeing when they encounter them in the wild. I think you have a good idea but this lesson may not be the right place for it. Also, I don't know if this is a real convention or just my habit but have only seen readme and README, not the camel case ReadMe.

I think it may be too much to add to the lesson but here are some reasons I have used .gitkeep

1. When starting a project, so I can have the full directory structure of the code fixed before the code has been written to populate it
2. When something is going to be machine generated and I want to guarantee the folder will be there, i.e. my tests sometimes generate figures to include in the documentation. I have an empty _autodata folder in my git repo so that all my tests and documentation can be written to access it and I don't need to write code to test if the folder exists into every test (the tests can execute in arbitrary order)

Those are weird reasons that go beyond the scope of the lesson but they are just to show that there are some good reasons for .gitkeep files

[nhejazi]

I think perhaps others should weigh in here but I do still see value in the use of .gitkeep files. The question of whether to use .gitkeep vs README.md (or .txt or w/e) comes down to the type of project as well as specifics on packages you might be relying on. README.md gets rendered nicely for someone browsing a project on GitHub, but it requires that the project developer author a file that explains exactly what the purpose of a given directory is, which adds additional overhead. For example, it's self-explanatory what a subdirectory figs/ will be used for, without the need to write a new README.md for the subdirectory (instead, the directory gets tracked by Git after a simple touch figs/.gitkeep). Also, as mentioned in comments in the linked issue, the use of README.md might cause problems with systems like Jekyll. In any case, I think it's worth possibly mentioning that creating a README.md is a more informative alternative to the use of .gitkeep but .gitkeep itself should still be mentioned as it was prior to the changes proposed in this PR.

[katrinleinweber]

Thanks for your replies! Yeah, the file should maybe named README-something.md in order to not conflict with the main README.md when copied into _site/ during a make procedure.

[...] directory structure of the code fixed before the code has been written to populate it.

I would argue that code which can take care of creating any folders it needs is better, because it's not coupled to the external factor of said file.

[...] I don't need to write code to test if the folder exists into every test

Sure, we want to be lazy, but coupling the test code to an external factor that is not really needed in the repo is a bit too lazy IMHO.

Functions that OTOH create files, but not the needed directory, should rather be identified and improved than worked around.

[scottgruber]

As mentioned in this thread knowing what a .gitkeep file is will help novices understand in case they run across it in a project using version control. I’m a new maintainer to this repository and trying to close issues and pull requests to clear the board. If there is any further comment please reopen.

[katrinleinweber]

Hi @scottgruber :wave: The proposed wording change would IMHO help to convey that knowledge. Please also note that Git's official docs don't mention gitkeep at all. Thus, some more guidance than the current, neutral statement of a fact seems sensible for a lesson.

I've replied to the remaining review comment above. Please reopen this and evaluate the PR's content.