Skip to content
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

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

Open
wants to merge 6 commits into
base: gh-pages
from

Conversation

@katrinleinweber
Copy link
Contributor

@katrinleinweber katrinleinweber commented Nov 2, 2018

Hi! Please see carpentries/lesson-example#234 for background on this suggestion. Cheers :-)

@steve855
Copy link

@steve855 steve855 commented Dec 21, 2018

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
Copy link
Member

@nhejazi nhejazi commented Dec 29, 2018

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
Copy link
Contributor Author

@katrinleinweber katrinleinweber commented Jan 8, 2019

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.

@katrinleinweber katrinleinweber changed the title Remove .gitkeep files and mention self-explanatory alternative WIP: Remove .gitkeep files and mention self-explanatory alternative Jan 8, 2019
Copy link
Member

@munkm munkm left a comment

I agree with @nhejazi about keeping .gitkeep explanations. I think the lesson could be enhanced by mentioning that README.md is additionally helpful to explain the intent of the folder, but the language around .gitkeep should remain the same as it is in the lesson currently.

> around by creating empty `.gitkeep` files if an otherwise empty folder is deemed
> to be tracked by Git. However, it's better to avoid this and look for ways to
> automatically create such folders when your code needs them, or try to very
> briefly explain the need for the empty folder with a `.keep-because-...` file.

This comment has been minimized.

@munkm

munkm Jan 23, 2019
Member

I understand your intention here by explaining the reason for .keep-because- to make the reason for having the .gitkeep file obvious. But in the wild I haven't seen any projects do this. Also .gitkeep is complimentary in naming to .gitignore. I disagree with incorporating the change as it is worded here. The original text says you can name them whatever you'd like without telling learners what they should be doing.

This comment has been minimized.

@katrinleinweber

katrinleinweber Jan 23, 2019
Author Contributor

How about the new wording?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants
You can’t perform that action at this time.