search

phyver / GameShell

a game to learn (or teach) how to use standard commands in a Unix shell
GNU General Public License v3.0
2.17k stars 138 forks source link

Improve the README.md #38

Closed bdchilton closed 3 years ago

bdchilton commented 3 years ago

The README.md is currently quite long, Rodolphe is thinking of changing a few things like adding a "getting started" section at the top for making it easier to quickly try the game.

rlepigre commented 3 years ago

I moved things form the README.md to the doc folder since I found it contained too much information (not great for someone who just want to quickly try the game). I organised the doc folder into two documents (linked from doc/README.md): a user manual and a user manual.

@phyver do we really want to keep a French version of README.md? (I fear it is gonna be a pain to keep in sync.)

phyver commented 3 years ago

Good job, it is clearer this way! I had a couple of corrections to add, but I can't push to the PR. I'm not quite sure what's the usual workflow: directly merge the PR, collaborate on this PR and them merge it, etc.

@phyver do we really want to keep a French version of README.md? (I fear it is gonna be a pain to keep in sync.)

I'm not sure. I think I'd prefer keeping a small README-fr.md. The new README.md is small enough that keeping the 2 in sync shouldn't be too troublesome. What do you think?

rlepigre commented 3 years ago

Good job, it is clearer this way! I had a couple of corrections to add, but I can't push to the PR. I'm not quite sure what's the usual workflow: directly merge the PR, collaborate on this PR and them merge it, etc.

I think you should be able to push to this PR: the person creating the PR can give the right to maintainers of the target repository to push to the branch (and it is the case here, I was able to push). However you need to add a new "remote" with:

git remote add bran git@github.com:bdchilton/GameShell.git
git fetch bran

And then you should be able to push to bran/readme.

@phyver do we really want to keep a French version of README.md? (I fear it is gonna be a pain to keep in sync.)

I'm not sure. I think I'd prefer keeping a small README-fr.md. The new README.md is small enough that keeping the 2 in sync shouldn't be too troublesome. What do you think?

OK, let's keep it for now, I agree that it is not too bad since it is quite short.

rlepigre commented 3 years ago

@bdchilton could you check the end of the README.md when you have a moment? You should be able to edit it at: https://github.com/bdchilton/GameShell/edit/readme/README.md.

phyver commented 3 years ago

@rlepigre did you try using termtosvg to create something?

Oh, and the macOS test is now working again!

rlepigre commented 3 years ago

@rlepigre did you try using termtosvg to create something?

I tried at some point, and it worked pretty well. Are you thinking of adding a generated image to README.md? If we want to do that, an alternative would be to record a video of the terminal window and turn it into an animated GIF, which will definitely be supported by more browsers.

Oh, and the macOS test is now working again!

Cool! I just removed the "debugging" workflow so that we get the green light for everything.

rlepigre commented 3 years ago

@phyver I think we are almost ready to merge. Could you review the French version of the README?

phyver commented 3 years ago

@rlepigre git question

So, I have 2 main branches: master and devel. I usually push to devel often, and to master less often.

I did merge this PR on master witouth problem, but then, master and devel started diverging.

What's the usual worflow for that? Is there an alternative to git merge master on devel, adding a 'merge commit' that gets propagated back to master when I sync everything?

Also, I use a tmp branch that it don't hesitate to --force push to. I mainly use it when I try debuging the test workflow and am pushing dozens of very small commits. That's not very clean, but I don't see a nice alternative...

rlepigre commented 3 years ago

So, I have 2 main branches: master and devel. I usually push to devel often, and to master less often.

I did merge this PR on master witouth problem, but then, master and devel started diverging.

What's the usual worflow for that? Is there an alternative to git merge master on devel, adding a 'merge commit' that gets propagated back to master when I sync everything?

Yeah, it is quite usual in projects to never push merge commits to master. In that case you need to always do git pull --rebase instead of git pull (to avoid merge commits when working concurrently on a branch), and when you want to sync with master you do git rebase master. In both cases, if something goes wrong, you can cancel the rebase with git rebase --abort (if I remember well, but git status usually tells you what you can do).

Note that you can configure git globally so that it always do git pull --rebase by default on git pull (I think it should be git config --global pull.rebase true).

Also, I use a tmp branch that it don't hesitate to --force push to. I mainly use it when I try debuging the test workflow and am pushing dozens of very small commits. That's not very clean, but I don't see a nice alternative...

Yeah, I tend to force-push like that often. An alternative is to push independent junk commits, and then squash them / delete them before integrating. I also do that sometimes, which also gives me a chance to clean up the history. To do that you can do git rebase -i master, and you can choose what to do for each commit (but I guess you used that before?).

Sometimes, it also makes sense to squash a whole branch when merging a PR (typically if it is small enough, and if all but the first commit were corrections).

rlepigre commented 3 years ago

Also, there are quite a few options to protect master and prevent mistakes: https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule (I cannot configure these since I do not have enough rights on the repo).

phyver commented 3 years ago

Thanks! I'll have a look.