Procedure questions on a GitHub Pull Request from a first time total noob

Tue 2018.10.30

Where/how do I obtain feedback on a pull-request at GitHub?

ref: http://www.espruino.com/Writing+Modules

Attempting to get/understand feedback on the submittal/approval process after following the above steps. I waited 48 hours before creating this forum post as not to show too much impatience.

Should I inspect the Pull Requests tab, I see 0 Open 1 Closed which is a bit mis-leading as; Is the pull process closed on the request I made, meaning no further action is/will to be taken or just an ack that the files are in the pipeline, so the
actual pull request is no longer needed?

If I navigate back to the pull request page from two days ago,

I can get to a page that indicates I did something, but unable to see what it is I actually did.

merged commit 14618de into master 2 days ago

so, is this the master folder of my forked copy or the master folder of espruino/EspruinoDocs ?
e.g. Did I goof somewhere and create a pull action into my own /EspruinoDocs copy?

I think I'm on the right track as if I go to:

https://github.com/espruino/EspruinoDocs

and attempt a pull request, I can only push files which agrees with the 'Writing+Modules' content, not mentioning the word 'push' This then implies, that my process is what was intended to have happened.

If everything is going as planned, about how long is the normal cycle time, as I guess there is a review and sanitizing step in the works, before finalization?

Is there a way to review the actual original pull request?

Where am I able to get feedback on the process at GitHub? . . . . and what/where should I be looking out for?

How long is the red carpet? Black tie and tails? and how large a band should I consider? Black Dyke Mills from the sixties (Jim Shepherd) my favorite. Are horses out of the question during pinning of the OBE and 21 cannon salute?

Thanks for any kind thoughts and words of wisdom.

I think you created a pull request on your own personal fork?

If you look at https://github.com/espruino/EspruinoDocs/pulls you'll see that there is no Pull request from you there. If there was, I'd be notified.

It looks from your fork https://github.com/sleuthware/EspruinoDocs/branches (is that you?) that you created a branch and merged it into your fork. If you clicked new pull request while looking at the master branch (or the one you care about) then it should give you the option of creating a pull request on the main repo.

Once you have done it, the answer is really 'it depends' - simple stuff can get merged within a few minutes, otherwise it can take a few days - weeks if I'm busy.

Looking at the diffs in your case, you'd probably need to remove a few extra files you have there:

• the html files
  
• the modules/test*.js files
  
• modules/codeNeopixelEx3.js and it looks like a few other files, that seem to be snippets of code you're using for testing?
  
  

Generally people send PRs for small things at once - one module and the docs for it. Since it looks like your PR has 25 files in it, I'll have to find time to go through and figure out what is/isn't needed - if you could try and issue PRs for smaller bits at once (eg. Colors) that makes life a lot easier.

Thr 2018.11.01

' I'll have to find time to go through and figure out what is/isn't needed '

There are only four code files, (dependencies see NeopixelQuickStart.js) and three doc files. No edits to existing files.

I thought I had it, then it appears to get worse.

I created a new branch Neopixel20181101 and added the seven unique new files, project complete, that I intend to create the request on; of which there are three modules, three corresponding markdowns, and a sample code usage file.

But, when I created the pull request on just that branch, GitHub is attempting to add 67 other files, which weren't part of what I had just uploaded. Was this a result of previously uploading files with similar names to perform remote testing (more below)?

Also, there now is a strange error: 'Merging is blocked'

Neopixel20181101 #462

Open sleuthware wants to merge 74 commits into espruino:master from sleuthware:Neopixel20181101

on the same page:

Merging is blocked

The base branch restricts merging to authorized users. Learn more about protected branches.
You’re not authorized to merge this pull request.

I scrapped completing the pull request.

Time to consider that it appears this fork may be corrupt.

Note: While I had used the \EspruinoDocs\modules folder in my fork to perform testing, that was done as the IDE wasn't allowing mapping of the \modules and \projects folders within a Windows documents folder. My only option to use local module files at all.

ref: http://forum.espruino.com/comments/14447493/

As that is now resolved and I'm able to load modules locally now, other than using that area for remote require() module testing, I am at a point considering scrapping the works. I'm truly only out the time I'll need to re-upload files under test.

Should this be considered at this time? e.g. starting over by deleting the entire EspruinoDocs copy and create a new forked copy

You did succeed in opening a pull request. I guess it's possible that the one you opened was from the master branch, and then it blocked you opening another?

Honestly though I can't be much help with GitHub - there's loads of stuff online about how to use it.

Can you post up a list of files you actually want and I can delete the others from your pull request manually before merging? I'm unlikely to get it done this week though as I'm away at a conference

Sun 2018.11.04

Thank you for the busy week notification.

'You did succeed in opening a pull request'

No, the buttons are not illuminated to continue, but

'Merging is blocked The base branch restricts merging to authorized users'

https://github.com/espruino/EspruinoDocs

does show the request was attempted.

https://help.github.com/articles/github-flow/
https://help.github.com/articles/about-pull-requests/
https://help.github.com/articles/creating-a-pull-request-from-a-fork/

After reviewing the above and attempting to clone a copy of EspruinoDocs in a unique new fork, resulted in the inablity to create a pull request into the espruino\EspruinoDocs\ branch. Forking a copy per instructions at Writing+Modules only pulls a copy on top of the current suspect corrupt copy. So, it appears that one may only create a pull request on a forked original copy, which makes sense.

To the software gods, I concede.

Have answered my own suspicion an am deleting the original suspect corrupt forked copy and starting over with a fresh forked copy. Good bye all that litter!

This should make everything easier having only one upload of unique new files to deal with.

Have fun at the conference and that should give me enough time to get a first tutorial done.

Hi @Robin, let me share how I do it when there are more than one file to add or to change.

So let do an example for EspruinoDocs.

• you can use git command tool or GitHub Desktop it's up to you

• clone EspruinoDocs to your local filesystem into directory EspruinoDocs

  git clone https://github.com/espruino/EspruinoDocs.git

• than create a branch for your changes with a suitable name so Gordon can identify what is inside

  git checkout -b Your_Brach_Name

• add or change what you like to share

• use git or GitHup Desktop to push your stuff and add some description

• than on GitHub create a pull request and select your branch

• after it has been merged you can delete your branch on GitHub

Please let me know if this works for you.

Mon 2018.11.05

Thank you @MaBe for your concise and explicit instructions. That detail will serve others as well, when this thread is discovered.

Although I have an online GitHub acct, essentially the order you describe and using a new branch container, is what I am doing.

Viewing the pull request tab at:

https://github.com/espruino/EspruinoDocs

I don't understand why there are additional multiple files added, and keeps growing, when I create the pull request though. It is possible this is left over litter from months of upload testing I did a year ago, when I had the local module folder debacle. That is the only thing that makes sense.

To clarify:

(sic - ref then) 'than on GitHub create a pull request and select your branch'

Presumably, the pull request is:
    from the espruino\EspruinoDocs side   ?    to allow the branch compare, and to find my forked copy?
As opposed from my online acct side, as it doesn't appear that the espruino source can be linked to?

I will attempt a local copy of GitHub, should this next attempt fall short.

I have seen your keen interest in matrix Neopixel projects over the last year. Phase III of this deployment intends to add user defined effects to the tutorial (underway as we speak) to show off Espruino's talent and capabilities. My Phase I part is keyed in to just Neopixel strips with effects along with user defined content. I hadn't considered matrix layouts and sure could use your input here.


As Gordon is busy until after this weekend, and I don't have available time until then either, this merge is now delayed week(s) in any event.


Would you like to review/test a quick-start demo code file that incorporates those modules; a'la MaBe StopWatch inspiration, to add your expert advice, constructive criticism, comments of any flavor, as to improve the quick-start file and offer suggestions to improvements, omissions etc. to the overall project . . . . before my final upload to the EspruinoDocs master? I have verbose comments included and JSDoc function header .html to go with that.

My overall goal is to include some matrix flavor enhancements, down the road in Phase III, and it just might be that, as you have a 'wealth of insight' (e.g. read into - snippets, code examples, etc) to add here. Honestly, I really don't have an inkling to dink with the matrix stuff, just doesn't impress me at the moment. Would love to hear your take on this objective also.

Robin

@MaBe, #6 implies for me that @Robin would have write rights to https://github.com/espruino/EspruinoDocs­.git.

As far as I know only a few have write access to https://github.com/espruino/EspruinoDocs­.git

The majority works through a fork of https://github.com/espruino/EspruinoDocs­.git placed into their own github account (their own remote repository) / repository space.

For the steps below, assume github account ao: github.com/ao/EspruionoDocs.

Steps - in git Web UI and terminal / command window:

1. fork .../espruiono/EspruinoDocs into .../ao/EspruinoDocs in git Web UI
   
2. From such remote, master is cloned into the local w/ git clone ...
   
3. A branch is checked out - created - on local w/ git checkout -b feature/fun (switching between branches is without -b)
   
4. Files are changed / deleted / added
   
5. Changed files can be listed w/ git status
   
6. Changes in files can be displayed w/ git diff
   
7. Commit-worthy changed files from list in 4. are added to the staging area w/ git add ...
   
8. Staged files are committed (locally) w/ git commit -m "commit message about the change"
   
9. The local commit is then pushed to remote (the fork) w/ git push
   
10. In github Web UI on remote repo / fork of oa, a merge request (MR) is created from pushed branch
    a) to master of fork - .../ao/EspruinoDocs - and also
    b) to master of origin - .../espruinoDocs.
    
11. MR towards master of fork is merged (can be merged by ao, because ao is the owner if the repo)
    
12. MR towards master of origin cannot be merged by ao. @Gordon has to do that because it is 'his' - locked down - repo.
    
    

The reason for making MRs from feature branches of fork and not from master branch of fork (after merging of feature branch) is that there may be multiple feature branches in different stages in the fork, but only the desired and completed should go into the MR towards the master of the origin. It may well be that some feature branches never even make it beyond being branches on the fork.

9.a) is not required. The changes will come with the update of the fork into the fork. The changes may be changed because most likely @Gorden will make some changes to the MRed feature branch before merging it into the origin.

Do I miss something here? Is there a shorter, more direct path?

(...somehow the post got unintentionally duplicated... so did split it...)

After @Gordon has performed the MR into his .../espruino/espruinoDocs repos - either unchanged or most likely with some changes, everyone else's fork has now to be updated w/ @Gordon 's commits. This will also bring all the new stuff into the fork

I have my way of updating my fork... but there may be better ones. The simple one - delete the fork and forking again works for sure, but only when nothing else is pending in repo, such as other feature branches or MRs of them - branches already pushed, but not made merge requests of yet, or not even done with development yet.

Updating a fork from origin in detail... that's a topic for a next post.

You should really do the GitHub PR as @allObjects says -so git clone you OWN fork, not espruino/EspruinoDocs and then work on that and issue a PR on the main Espruino repo from your personal fork.

@MaBe ideally you wouldn't actually do it the way you suggested - because all the work in progress forks end up public and on the main Espruino repo.

Wed 2018.11.07

'because all the work in progress forks end up public'

Most likely why I'm seeing 60+ changes/files appended with the desired branch during PR

Thank you @allObjects for the numbered instructions with annotations. That should help us all refer to a common sequence step.

I asked this several times, but still not sure if this will have caused issues, See #7 pull request above:

ref: http://www.espruino.com/Writing+Modules

I made it to the third from the end line:

'When you have it all as you want, . . . . click on Pull Request'

but the buttons were un-hilighted, so was unable to continue.

So, the Weekend Plan:

Start early, hot pot of coffee, phone off hook, loud Rock-n-Roll,
start with 1972 Steely Dan - Reelin' In the Years, (turn up volume before clicking play for best guitar riff intro effect)

https://www.youtube.com/watch?v=_bwHK1xkgJA

Rev   'er up, dump the clutch,    begin . . . .


1) Delete old repo
If all goes well and above PR attempt doesn't block progress:
2) Create forked copy
3) Create clone of that
Using ao 10, 11, 12
4) Create branch and add files - commit
5) Create Pull Request from clone to fork
6) Create Pull Request from fork to espruino\EspruinoDocs

If that fails, or a hint of, 2nd pot of coffee, louder Rock-n-Roll

Read up on and install local copy and start with ao 1)

Have I got it?

I asked this several times, but still not sure if this will have caused issues

As I said before, this may well be because you had already opened a pull request from your repo's master branch that you hadn't closed. I've just closed it for you just in case.

4) Create branch and add files - commit
5) Create Pull Request from clone to fork
6) Create Pull Request from fork to espruino\EspruinoDocs

You shouldn't need step 5. Commit the files in your cloned repo's branch, then do git push. Once that's done you should be able to visit your branch in GitHub and click the pull request button.

Can we stick with one kind of numbering of the steps? ...so the contributions can augment one other? I'll gladly adjust the list in post #8 with what ever it takes to get it ready for extraction for a tutorial or at least a separate conversation. If an step is 'too big', we can cut it, or add sub items, such as a) b) c)... I also like to add examples

Honestly, @Robin should just use your steps @allObjects exactly as I believe they're spot on.

I was just trying to correct Robin's post where he was suggesting he do something different.

...yes, sometimes some terms get clobbered up... but they will un-knot on the go... ;-)

Sat 2018.11.10

Two pots of coffee and the music helped!!

From #9

'delete the fork . . . . but only when nothing else is pending in repo'

https://help.github.com/articles/deleting-a-repository/
https://help.github.com/articles/deleting-and-restoring-branches-in-a-pull-request/

'You cannot delete branches that are associated with open pull requests.'

Although it would have been nice to test if GitHub would stop/block the repo deletion as there was an in process branch PR, we'll have to take their docs at face value. As I couldn't close (the buttons were not illuminated) maybe I could have (then), deleted the branch perhaps, then deleted the repo?

Interesting note. I first renamed (as I didn't want to have to re-upload other project test files) the suspect corrupt fork. I then attempted to create a new fork. GitHub just made a fork copy over the renamed one and not a unique new instance. I'm forced to delete the renamed one first.

from #13 'Can we stick with one kind of numbering of the steps?'

Yes. @allObjects use your numbering for a local install of a GitHub repository. The following with annotations may be used to create documentation for those that wish to use a public online fork. Both advantages and dis-advantages. I left off numbering so as not to conflict with a chosen system.

Note: Formatting this was a pain - indenting not recognized in list - it is what it is . . . .

Using a public online fork - uses button clicks as opposed to manually entering git commands

• Create fork
  
  

https://github.com/espruino/EspruinoDocs/

In upper right hand corner click on 'fork'

• Create Clone
  Click on Green 'Clone or Download' just below 'View License' tab

• Create Branch

  https://help.github.com/desktop/guides/contributing-to-projects/creating-a-branch-for-your-work/

Click on 'Branch Master' to enter a unique new branch
Click the 'Current Branch' icon to view existing branches

• Add Files
  Navigate to 'modules' folder (or 'devices')
  
  

EspruinoDocs/modules

Within the branch just created, select 'Code' tab and upload files by clicking 'Upload Files' button located in block of four buttons close to page top in upper right just below 'contributors' tab

Enter simple description

Click 'Commit' button

• PR - Pull Request
  
  

Create the pull request to merge branch into personal fork master copy
Click 'New Pull Request' on left hand side just below 'Branches' tab

Select correct fork in button compare section near page top

https://github.com/ your name /EspruinoDocs/pull/

Click green 'Merge Pull Request'
Click green 'Confirm'

end PR

• Verify - Navigate to 'modules' folder to see files were in fact merged there

• As fork compare only allows from parent, navigate to: to merge those branches into that repo

  https://github.com/espruino/EspruinoDocs

• Start PR (above) from parent and select desired user fork in button(s) compare
  Continue with PR steps to pull fork update into espruino/EspruinoDocs master

• Verify - Navigate to app base and select 'Pull Requests' tab

  https://github.com/espruino/EspruinoDocs/pulls

Thank you @Gordon, @allObjects and @MaBe for your input.

Following thru as described in https://stackoverflow.com/questions/17268394/change-fork-name-for-github would have solved your issue / let you keep the old fork and let the local - your clone(s) and checked out branch(es) - on your local still in working condition (re-connected).

A a fork is actually not that much different than a plain repository. The only difference is that the fork has an origin where as the repos is the origin, and therefore a change(s) in the fork that should go to the origin has(have) have to go thru process of merge request (MR). A MR can have as much you put into it. The owner of the origin then can either accept the MR as is, apply modifications to the changes to some parts before accepting, accepting a part - called cherry picking or reject the MR all together.

Since the origin itself changes too and the MR when merged changed or partially is also a change versus what the fork 'knows', the fork has to be updated. I promised earlier to post about it... and it has to still stay a promise for now.

To get some understanding of the guts, take a look at this book... http://shop.oreilly.com/product/0636920022862.do - there are other good - and may be even free - books and tutorials out there... beyond the 10-day free Safari - read online - trial for this Oreilly book.

I found this git - the simple guide, introduced as (sorry for the wording, it is the author's subtitle):

just a simple guide for getting started with git. no deep shit ;)

It lacks some graphics to visualize 'the flow of things' and some basic text or reasoning for why this particular flow.

You can get that though together in you head with the simple fact about how edition id-ing works in git / gitlab / and the like - all based on Linus Thorwald's 'suggestion': the id of a new edition is construed from the previous id / parent id(s) and the new content - ids are also called commits or hashes - the latter hints how the id is constructed: it is actually calculated with an algorithm. I get it, you will say: every child knows the parent(s), and any parent was once a child (except it was the first of something... the empty repository. The ramifications show the ingenuity of this setup... in many aspects, for example:

1. If you and i have the same id, we know that you and I have the very same content.
   
2. There is nothing that can come out of thin air (except the first edition): everything is a very well trackable change to a previous edition (in case of the first thing, the empty repos is that previous thing).
   
3. Confidence - I do not need to got a check... and miss a thing because of my imperfectness
   
4. Performance - performance - performance... Since same hash means same content, no need for compare, which saves me time... not just for the compare, but I do not need to ship around and waste band with in order to know that it is the same or different and I need only what is different to have a complete pic of a new hash...
   
   

Btw, until recently there was only one content and id that together create one and only one, unique hash. You can also say just content and define the content to include the id... just like a data record in a reasonable (indexed) setup of a database, where the id is a part of that record. The existing uniqueness is though more than sufficient for source code - that is verbose, has syntax and berars semantic... A content that would result in the same hash but would be different would be absolutely different in regard of those aspects.

Sun 2018.11.11

'Following thru as described in . . . . would have solved your issue'

Nope. That stackoverflow link has the same content as at:

https://help.github.com/articles/renaming-a-repository/

Maybe on a local copy but remember I had a public online repo fork.

If you re-read 'Interesting note' above, you'll see that I attempted what is described. When attempting to get a new forked instance,
GitHub knew the origins of the renamed forked copy, and just created the new fork as a copy over the renamed one. Did this twice.

Reading the 'git - the simple guide' . . . .

@allObjekts
thanks for this complete step by step list. I have been using this for my fork of Espruino but ended up in a large list of changes including merges from the master. So I decides to close that PR's again and some times I asked Gordon to to cherry picking :-(

As far as I know only a few have write access to https://github.com/espruino/EspruinoDocs­.git

No every one is allowed.

@Gordon

@MaBe ideally you wouldn't actually do it the way you suggested - because all the work in progress forks end up public and on the main Espruino repo.

Ups, that was not planed, so let me close that PR and create a new one without progress stuff.

'As far as I know only a few have write access to '

Presumably, the three individuals under the 'People' tab of the repository list are with 'owner' privileges

https://github.com/espruino

https://help.github.com/articles/access-permissions-on-github/

@MaBe, everyone can create a merge request when it come from a fork of origin. With write access I meant that you can - at least - create branches in origin... does still not mean that you can merge merge requests...

@allObjects: Got you. Yes that is correct, AFAIK Gordon is the only one that can merge changes and I am glad about the way it is!