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

Make variables consistent and documented across cookiecutters #217

Open
3 tasks
timmc-edx opened this issue Jul 12, 2022 · 0 comments
Open
3 tasks

Make variables consistent and documented across cookiecutters #217

timmc-edx opened this issue Jul 12, 2022 · 0 comments

Comments

@timmc-edx
Copy link
Contributor

timmc-edx commented Jul 12, 2022

When using a cookiecutter, I'm presented with a lot of questions that I'm not really sure how to answer. For example, when using cookiecutter-django-app I'm asked to provide all three of repo_name, app_name, and project_name. Problems I have with this:

  • It's not entirely clear how these map to local directory name, GitHub repo name, Django app name (OK, this one is clear), root module name, and Python package name.
  • The mapping is apparently different in some places between cookiecutters.
  • It's not obvious which of these need to use underscore vs hyphen, or should be prefixed with edx/openedx, or should be punctuated as natural language ("edX Event Bus" vs "edx-event-bus").
  • Some fields need more explanation and guidance, such as the one asking for license selection (should link to wiki page) or author name and email (what is this used for?)
  • Some of the usages are also just wrong; see docs: Fix badges and other cookiecutter-created repo/package references event-bus-kafka#22 for an example of how GitHub repo name and Python package name were confused in the README.

It would be great if the prompts could include help text, but the cookiecutter library doesn't support this and probably won't any time soon.

Recommended work:

  • Ensure all variables are consistent across cookiecutters, as appropriate
  • Ensure variables are factored out appropriately (e.g. may need to split responsibility for package vs root module name)
  • Document variables in a new Variables section in the README, explaining what they're for and what guidelines should be followed for each one

(This work can be done incrementally.)

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

No branches or pull requests

2 participants