Improve first-time setup workflow

Open
#42 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
python
Domain
build-system, developer-experience

Research direction

Start with the make deps flow in Makefile, especially the command-output tasks at lines 211-225, and review the setup guidance in README.md. Compare the documented shell-rc approach with the proposed setup task, then define which approach should eliminate the repeated manual setup steps and how completion will be verified.

Written by the indexing model from the issue text.

Description

The first-time setup workflow as of initial public release is effectively:

  1. make deps, which will error if Homebrew isn't found.
    1. User must manually make install-homebrew to install Homebrew, then run make deps again
  2. make deps, via deps-brew will install deps from Homebrew including pyenv
  3. make deps, via install-python via deps-py, will install Python from pyenv, which will error if pyenv isn't found
    1. User must manually add pyenv loading code to shell rcfile, then run make deps again
  4. make deps, via install-poetry via deps-py, will install Poetry using pyenv-installed Python or system Python, whichever it detects first, and only if poetry isn't available as of the start of the current run of make.
  5. make deps, via poetry-install via deps-py, will install Python deps using Poetry, which will error if poetry isn't found
    1. User must manually add ~/.local/bin, Poetry's default installation path, to their PATH in shell rcfile, then run make deps again.
  6. Complete 🎉

There are some steps I skipped in here related to telling Poetry which Python to use (it generally just works) and sync'ing Peru (also generally just works).

These one-time setup steps ("user must manually…") are annoying. While some tasks tell the user that they need to read command output, too many users just… don't.

Possible solutions:

  1. Document most generic thing to pre-add to a user's shellrc file in README.md or at the end of make deps.
  2. Create a task make wreck-my-rcfile or maybe more nicely make setup-rcfile-once that modifies the shellrc with what should be put there carefully manually.
  3. No action: let the user suffer having ignored the nudge to read command output.
Dominant language
Makefile
Stars
31
Forks
6
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from target/make-python-devex

All issues in target/make-python-devex

Similar issues

More Build System issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.