Not Clear That You Can't Continue From Getting Started to Flavors

[ilyaigpetrov]

In the readme after completing Getting Started section I continue to Flavors:

1) hpal new my-project 2) cd ./my-project 3) git cherry-pick templated-site error: refusing to lose untracked file at 'server/manifest.js' 4) git add -A :/, git commit -m "blabla" 5) git cherry-pick templated-site error: after resolving the conflicts, mark the corrected paths

If I have to run git clone instead of hpal new my-project then it's not clear from the readme. Thank you for your work.

[ilyaigpetrov]

Ah, I had to resolve a package.json conflict in point 5). Please, make it more obvious that you have to commit files in case of Getting Started and resolve a conflict after cherry-pick.

[ilyaigpetrov]

Also, 1) git clone https://github.com/hapipal/boilerplate.git 2) cd boilerplate 3) git fetch pal --tags fatal: 'pal' does not appear to be a git repository 4)

cat .git/config 
[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = https://github.com/hapipal/boilerplate.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "pal"]
        remote = origin
        merge = refs/heads/pal

[devinivy]

Please, make it more obvious that you have to commit files in case of Getting Started and resolve a conflict after cherry-pick.

Yes, we should add the step to Getting Started of making an initial commit. I think that the tutorial makes it clear that conflicts may arise, but we'll revisit that to make sure. Feel free to suggest specific changes here https://github.com/hapipal/hapipal.com/blob/master/lib/content/getting-started.md.

fatal: 'pal' does not appear to be a git repository

The instructions should include --origin pal in the git clone command, so that this issue doesn't occur. The hpal CLI also ensures that fetching tags like this will work. Do you see instructions somewhere that omit --origin pal?

[ilyaigpetrov]

Do you see instructions somewhere that omit --origin pal?

From https://github.com/hapipal/boilerplate:

If you used the hpal CLI to create a new project then this should already be done for you. But you can always do it manually as well– simply pull down git tags from the pal remote.

git fetch pal --tags

So I decided to do it manually via cloning and faced that 'pal' does not appear to be a git repository.

[devinivy]

Sure, I understand that 👌 However, I don't see any ideal way around this. The manual cloning instructions in the readme, and the process taken by hpal new both ensure that the repo is cloned from a remote named "pal." The reason for this is that we assume you may want to create your own "origin" remote. All the instructions are meant to work well with each other, so git fetch pal --tags is written under the assumption that the name of the remote is "pal." What would you suggest be changed?

[devinivy]

(And in case you're still stuck, in your setup just fetch from origin instead: git fetch origin --tags.)

[ilyaigpetrov]

The manual cloning instructions in the readme...

There are no cloning instructions in the readme. I suggest adding them.

[devinivy]

Just click this line in the "Getting Started" section of the readme,

npx comes with npm 5.2+ and higher. here you can find instructions for older npm versions.

[devinivy]

I am going to leave this issue open to,

• [ ] Adjust the line in the readme "here you can find instructions for older npm versions" to also mention manual cloning instructions.
• [ ] Ensure the Getting Started tutorial is clear that conflicts may/will arise when pulling in multiple flavors.

[dirtybirdnj]

I was going to make an issue for this, but decided to check and found that someone else ran into the same issues I had.

My goal was to checkout the repo and switch between the provided tags/branches to view the different features. I get a git error I don't expect at all... I just checked out a repo and haven't made any changes yet it's telling me I have untracked stuff I have to commit?

It's confusing why you are requiring users to make a commit before they can switch to a different branch.

Also... even after adding my personal repo as a remote... making a commit and pushing the pal branch to my repo... I STILL get the same error trying to do git cherry-pick objection

error: could not apply 4543532... (flavor) objection v2.1.1
hint: after resolving the conflicts, mark the corrected paths
hint: with 'git add <paths>' or 'git rm <paths>'
hint: and commit the result with 'git commit'

[devinivy]

I just checked out a repo and haven't made any changes yet it's telling me I have untracked stuff I have to commit?

The hpal new command clones the boilerplate, writes the README and package.json with the project details you filled-out, and leaves you on master, but without any commit history. When I designed that command I thought that the user should be in charge of making the first commit to their project with any additional changes they might want—add more info to the readme, add dependencies to package.json, setup their environment file, fix a typo in their project's name, etc. This is just how I would expect/want it to work, but I'm only one person!

Luckily we have options! We can change the behavior to make the initial commit to the user's project. We can add that ability as a flag. We can improve the command's output and documentation to make this point more clear. It's possible we should open a new issue on hapipal/hpal if we want to consider options to change its behavior.

[dirtybirdnj]

I think the default behavior is very helpful, just unexpected!

The larger issue (to be resolved via clearer docs, or modifying default behavior) with requiring commits is that is that it prevents the user from following along with the documentation as-is because you don't explicitly state those steps have to be taken. It's my first day with this project, but I would definitely +1 your suggestion for implementing the "initialization files" stuff as a flag.

One additional thing I was trying to find associated with this was how to clone the existing repo but not bring along all the commits of the boilerplate project itself. Every which way I did it, running git log showed all the commits associated with the boilerplate. I tried using git clone $REPO --bare but that wasn't the right way to do it.

Git education isn't exactly the point of this project, but I hope that information is useful as well :)

[devinivy]

This is all useful feedback—thanks 👍

If you're still having trouble with that git business, here's how hpal approaches it,

git clone --depth=1 --origin=pal --branch=pal git@github.com:hapipal/boilerplate.git my-project
cd my-project
git checkout --orphan master # New branch without history

[dirtybirdnj]

@devinivy thank you for that super helpful git snippet! This did exactly what I was looking for.

The only thing I'd like to add (since we are ON github) is that anybody following these steps:

cd my-project
git checkout --orphan master # New branch without history

will have to go into the repo settings and change the default branch to master, otherwise after following the above steps and refreshing the github page for your repo, you'll still see the pal branch and all its commits by default.

I'm really excited about this project, when I was introduced to Hapi I was thrown into the deep end without much explanation or documentation. This project feels like the missing manual that maybe others didn't need but is a required learning tool for people like me. Implementation examples are worth their weight in gold! Especially when dealing with the transition from Hapi 16 => Hapi 17

[dirtybirdnj]

@devinivy I figured out what my problem was... I was just having trouble wrapping my brain around the cherry pick process / tag workflow. Once I figured that out I was able to cherry pick the features I want and diff/merge them into my personal branch it all clicked.

Rather than fill up the comment section here... I wrote an article about it please LMK what you think!

https://medium.com/@dirtybirdnj/command-blind-adj-why-you-get-stuck-following-instructions-you-find-online-2d2056925d3e

[devinivy]

Resolved in #65