Pull request method for correcting Cologne dictionaries

[drdhaval2785]

This issue is dedicated to give a step by step visual guide to a user wanting to submit batch of error correction via git and github on a regular manner.

For this example, we would make the following correction

Dictionary - MW72
headword - atipraRAS
See https://www.sanskrit-lexicon.uni-koeln.de/scans/MW72Scan/2014/web/webtc/indexcaller.php?key=atipraRAS&input=slp1&output=SktDevaUnicode
This gives the following result.

अतिप्रणाश् [Cologne record ID=737] [Printed book page 0015-a]अतिप्रणाश् ati-pra-ṇaś (rt. naś), cl. 4. P.-ṇaśyati, -ṇaśitum or -ṇaṃṣṭum, to be deprivedof (with acc.).

When it is crosschecked with the scan at https://www.sanskrit-lexicon.uni-koeln.de/scans/awork/apidev/servepdf.php?dict=MW72&key=atipraRAS , it gives the following.

On examining the scan, it is verified that the headword needs correction from atipraRAS to atipraRaS.

The following issue would make a step by step visual instruction to make such a correction and let the maintainers of Cologne dictionaries know about it by a pull request.

[drdhaval2785]

Prerequisites

1. You should have git installed in your computer. Read English word Corrections and Git #23 for details.
2. You should have a github account.

[drdhaval2785]

Step 1

1. Sign in to your github account with your username and password.

[drdhaval2785]

Step 2

1. Go to https://github.com/sanskrit-lexicon/csl-orig
2. Click on 'fork' button on right side of the page, as shown in the figure below.

3. If you are member of various organizations, you will be asked to select where you want to fork. You should fork it to your own username. In my case, I should fork it to drdhaval2785.
   

4. This shall create your own copy of csl-orig repository. It would be available at https://github.com/{USERNAME}/csl-orig . In my case it would be available at https://github.com/drdhaval2785/csl-orig.

[drdhaval2785]

Step 3

1. Open your fork of csl-orig (In my case https://github.com/drdhaval2785/csl-orig).

2. Click on 'Code' button on the right side.
   

3. Select the line in 'HTTPS' tab, and copy it by Ctrl-C or clicking on clipboard icon.
   

[drdhaval2785]

Step 4

1. Create a folder named 'cologne' at a convenient place. (I have created it at Desktop/cologne).
2. Open 'Git Bash'.

3. Type cd /path/to/directory and press ENTER. In my case it would be cd Desktop/cologne.

4. Type git clone https://github.com/{USERNAME}/csl-orig.git and press ENTER. In my case, it would be git clone https://github.com/drdhaval2785/csl-orig.git. Make sure to type your own username. The line after git clone would be the same as what we had copied from step 3.3. Wait for the process to end. At the end, the screen would show something like this.

5. This means that you now have your own copy of csl-orig repository in your computer.

[drdhaval2785]

Step 5

1. Open your file editor, and reach to the dictionary which you want to edit. Path would be cologne/csl-orig/v02/{DICT}. In our example, we want to edit the mw72 dictionary. Therefore, we will go to cologne/csl-orig/v02/mw72 folder.
   

2. Open DICT.txt file in the text editor of your choice. In our case, it would be mw72.txt file. I am using notepad++. You may use notepad++, emeditor, emacs. Simple notepad usually hangs. Therefore, its use is not recommended.

3. Search for the entry you want to correct. In our case, we want to correct atipraRAS entry.
   

4. Make necessary corrections in the entry.
   OLD ENTRY

<L>737<pc>0015-a<k1>atipraRAS<k2>atipraRAS
{#atipraRAS#}¦ {%ati-pra-ṇaś%} (rt. {%naś%}), cl. 4. P.
<div n="lb"/>{%-ṇaśyati, -ṇaśitum%} or {%-ṇaṃṣṭum,%} to be deprived
<div n="lb"/>of (with acc.).
<LEND>

CORRECTED ENTRY

<L>737<pc>0015-a<k1>atipraRaS<k2>atipraRaS
{#atipraRaS#}¦ {%ati-pra-ṇaś%} (rt. {%naś%}), cl. 4. P.
<div n="lb"/>{%-ṇaśyati, -ṇaśitum%} or {%-ṇaṃṣṭum,%} to be deprived
<div n="lb"/>of (with acc.).
<LEND>

5. Save the file.

[drdhaval2785]

Step 6

1. Open 'git bash'

2. Reach the csl-orig repository by cd /path/to/repository e.g. cd Desktop/cologne/csl-orig.

3. Type git status. This will show you the changed file in red colour.
   

4. Type git diff. This will show you the changes you made to the file.

points 3 and 4 are just for sanity check to see if you are actually sending only the desired corrections or not.

5. Type git add .
6. Type git commit -m "CORRECTION MESSAGE". In our case, I am sending the message 'MW72 atipraRAS->atipraRAS'. So the command would be git commit -m "MW72 atipraRAS->atipraRaS"
   

7. Type git push origin master. Type your username and password when prompted.
   

8. Wait for the process to end. You will see something like this.
   

You have successfully uploaded the change to your copy of csl-orig i.e. drdhaval2785/csl-orig.
Now it is time to notify that change to sanskrit-lexicon/csl-orig via a pull request.
That would be handled in the next step.

[drdhaval2785]

Step 7

1. Open https://github.com/{USERNAME}/csl-orig . In our case, it is https://github.com/drdhaval2785/csl-orig.
2. Look at the highlighted line. It will tell you that you have committed something which is not yet incorporated at sanskrit-lexion/csl-orig.

3. Click on 'Pull Request' button on the right side.
   

4. Click on 'Create Pull Request' button.
   

5. Once again, click on 'Create Pull Request' button. You can also write some message if you wish to, but it is optional.

6. You have now successfully created a pull request.

7. Maintainers of sanskrit-lexicon/csl-orig repository can see your pull request. If found OK, they can merge this pull request, and your change would be available in sanskrit-lexicon/csl-orig repository.

[gasyoun]

This issue is dedicated to give a step by step visual guide to a user wanting to submit error correction via git and github.

I would say a batch of errors on a regular manner.

[drdhaval2785]

@sanskritisampada would also be a candidate. Maybe Usha also.

[gasyoun]

If found OK, they can merge this pull request, and your change would be available in sanskrit-lexicon/csl-orig repository.

In a week or so.

@sanskritisampada would also be a candidate. Maybe Usha also.

Let us try the Desktop approach with Usha, it does get a bit harsh with a console.

[drdhaval2785]

Congratulations @AnnaRybakovaT for your first pull request.
Now you are familiar with the functioning of pull requests. You can now send batches of 20 or so corrections in a single pull request.

@funderburkjim Are you OK with this method of correction submission?
In case there are any discussions (think of notes after semicolon in our old system), we can discuss the same in 'conversation' portion of pull request.

[funderburkjim]

@drdhaval2785

A couple of years ago, you urged that I trade in my horse and buggy for a shiny new git-mobile.

After some growing pains, I finally came to love it.

Now, you're pointing out the new pull-request gadget which I have never made use of.

Probably I'll come to love it, also. Willing to give a try.

I'm sure some new questions/concerns will initially arise.

[funderburkjim]

Notification question

I have no email notification regarding either the pull request that Anna made, or your merge of the
pull request.

The only way I know that something happened to csl-orig is by looking at it in Github.

[funderburkjim]

multiple batch question

Suppose Anna or Sampada do several batches of corrections.

In detail, suppose Anna has done a fork of csl-orig, cloned it to her local computer, made
Batch 1 of corrections to MW local csl-orig, and made a pull request.

Suppose she then makes a comment in a Github issue to notify me of this pull request.

Next day she wants to start on Batch 2. Where does she start? Does she do another fork
of csl-orig? How does that work ?

[gasyoun]

A couple of years ago, you urged that I trade in my horse and buggy for a shiny new git-mobile.

And now he offers you Ford Model T. It will add millions of updates to my github panel, still.

[drdhaval2785]

Notification question

I received the usual mail notification.
You did not get the notification, because you are not watching the csl-orig repository. Check https://github.com/sanskrit-lexicon/csl-orig/watchers . I am the only member who is watching this repository.

You may click on the 'Watch' button on right upper corner, and you should receive all the notifications.

[drdhaval2785]

multiple batch question
Next day she wants to start on Batch 2. Where does she start? Does she do another fork
of csl-orig? How does that work ?

She can continue to work in her local copy. She can create changes, git add ., git commit -m "blah blah", git push origin master to her https://github.com/AnnaRybakovaT/csl-orig
Once her fork has those changes, she can once again create a pull request.

[drdhaval2785]

Upadate your fork (Background)

Based on https://stackoverflow.com/questions/20984802/how-can-i-keep-my-fork-in-sync-without-adding-a-separate-remote/21131381#21131381

There are cases where your fork https://github.com/drdhaval2785/csl-orig does not contain the changes made to the original repository https://github.com/sanskrit-lexicon/csl-orig .
It is most probably due to some other contributor submitting a change on https://github.com/sanskrit-lexicon/csl-orig .

A similar case presented itself in our exercise.

@AnnaRybakovaT submitted a correction in mw72.txt via sanskrit-lexicon/csl-orig#432 and @funderburkjim made various changes to ap90.txt file like sanskrit-lexicon/csl-orig@ccd4740 .

These two changes are existing on https://github.com/sanskrit-lexicon/csl-orig , but are absent from my fork https://github.com/drdhaval2785/csl-orig .
To get the maximum out of the updates on the original repository, I need to (1) Update my fork https://github.com/drdhaval2785/csl-orig to have the changes mentioned above and (2) Update my local files to have those changes.

The next comments would give a visual guide for the same

NOTE - It is advisable to have the fork synced and local files updated before starting any new corrections.

[drdhaval2785]

Update Forked Repo (Step 1)

1. Open your fork on Github - https://github.com/{USERNAME}/csl-orig e.g. https://github.com/drdhaval2785/csl-orig

2. This will show whether your fork is behind the master or not.
   

3. If it is behind the master, click on 'Pull Request' as highlighted below.
   

4. Click on 'switching the base'
   

5. You should be able to see (1) commits which are different between your repo and original repo. (2) Difference in files. They are marked with 1 and 2 in the below image. Check the differences. Once you are OK with the changes, move to the next point.
   

6. Click on 'Create Pull Request'
   

7. You shall see a window like the one given below. (1) If there are no clashes, there will be a message Able to merge. These branches can be automatically merged.. It is safe to merge this pull request. If there is any other message, STOP. (2) Write some useful name for the pull request. I have written pull ap90.txt and mw72.txt changes. (3) Click on 'Create Pull Request'.
   

8. Click on Merge Pull Request and Create a merge commit
   

9. Click on 'Confirm merge'.
   

10. The pull request is now merged in https://github.com/drdhaval2785/csl-orig
    

Now my forked repository has all the changes made to https://github.com/sanskrit-lexicon/csl-orig

11. Verify that your fork has desired changes (Not required. This is for extra precaution)
    

And click on the commit. This shows the differences which are added via this updation process. Everything seems fine. My fork now has all the changes made by original repository.

[drdhaval2785]

Update Forked Repo (Step 2)

In this step, we will update our local files based on updated https://github.com/drdhaval2785/csl-orig via Step 1.

1. Open Git Bash.
2. cd /path/to/repository
3. git status . If there are any changes which are not committed, it will be shown. Then you should do git add . and git commit -m "commit message". If there are no uncommitted changes, you will see a message Your branch is up to date with 'origin/master'. nothing to commit, working tree clean. Then proceed to step 4.
4. git pull origin master

[drdhaval2785]

@funderburkjim
I hope that above messages will help @AnnaRybakovaT and anyone else working with forked csl-orig repository to update his / her repository when there are new changes on sanskrit-lexicon/csl-orig repository.
Anna may give it a try, and update her fork to be up to date with changes in ap90.txt made by Jim.

[gasyoun]

Anna may give it a try, and update her fork to be up to date with changes in ap90.txt made by Jim.

Documented well, but would not say it's easy to grasp, let us see, until now Anna never failed to, thanks.

[AnnaRybakovaT]

Anna may give it a try, and update her fork to be up to date with changes in ap90.txt made by Jim.

OK. I will try.

[AnnaRybakovaT]

I have started the Step 1.
Until 1.7 everything was fine but in 1.8 I stopped since after clicking on "Create a merge commit" - nothing happening

[funderburkjim]

You may click on the 'Watch' button.

Done Watching 'all activity' for csl-orig. Thanks.

[funderburkjim]

Instructions on keeping forked csl-orig in sync with master csl-orig very useful.

But there are some edge cases in the 'merge' process that could require further attention. 'Git' is very complete -- after all
it was developed by Linus Torvalds for maintaining Linux, which has probably thousands of collaborators; so Git can handle
basically any situation. But there do arise situations (such as when person A and person B make a change to the same line
in a file) whose resolution is difficult. But these are thankfully rare; and we don't have to completely understand at the
beginning every single case.

In regard to 'Update Forked Repo (Step 2). items 3 and 4' (comment above)

Step 2 is about pulling the merged fork to our local machine. I actually think it does not matter whether 3 is done before 4.
In other words, I think we could just as well do the 'git pull' first. Then sometime later do git add, git commit.

[funderburkjim]

https://github.com/AnnaRybakovaT/csl-orig (Anna's fork of sanskrit-lexicon/csl-orig) shows
This branch is 5 commits behind sanskrit-lexicon:master.

[drdhaval2785]

@AnnaRybakovaT
n step 1.8, you needed to Click on Merge Pull Request and Create a merge commit.
When you click on Merge Pull Request, there will be a drop down Create a merge commit. You need to select that in dropdown.

[gasyoun]

But there do arise situations (such as when person A and person B make a change to the same line
in a file) whose resolution is difficult.

Rare is the word.

[AnnaRybakovaT]

When you click on Merge Pull Request, there will be a drop down Create a merge commit. You need to select that in dropdown.

Yes, I see and click "Create a merge commit" - but no result.

[AnnaRybakovaT]

As well today I see the new 3 commits

[drdhaval2785]

Hi Anna,
Your pull request was created successfully at AnnaRybakovaT/csl-orig#1. Now you need to merge the same.

[drdhaval2785]

[drdhaval2785]

[drdhaval2785]

As I do not have write access to your repository, I am not getting any facility to merge the same. You must be getting some button to merge the pull request at the bottom (after the place to write message).

[AnnaRybakovaT]

You must be getting some button to merge the pull request at the bottom (after the place to write message).

Unfortunately, I don't see anything like this

[AnnaRybakovaT]

I found solution!!!!
I have to click one more time on "Merge pull request" (after activation "create a merge commit")

[AnnaRybakovaT]

So the Step 1 has done. I will make the Step 2 in a while.

[AnnaRybakovaT]

Dear all,

The Step 2 is done as well.
There was a message: Your branch is up to date with 'origin/master'. nothing to commit, working tree clean. So after "git status" I put straightly "git pull origin master"

[gasyoun]

The Step 2 is done as well.

You've become a coder by now, I congratulate you.

[drdhaval2785]

Updating a forked repo (When both ahead and behind)

Recently @AnnaRybakovaT referred to a situation where her repo was X commits ahead and Y commits behind the original repository.
This issue tries to replicate similar situation for https://github.com/drdhaval2785/csl-orig and try to find a solution.
I have made a small correction regarding a single entry in PE in my fork. See #35 for error corrected.
I have pushed that change to https://github.com/drdhaval2785/csl-orig

1. Check the status of your repository (whether ahead or behind of sanskrit-lexicon/csl-orig). In my case, it is 1 commit ahead and 3 commits behind the master.
   

2. Click on 'Pull Request'
   

3. You will see 'base repository' i.e. the repository on which the pull request is to be made, and 'head repository' i.e. the repository from which the pull request is to be made. In default case, it mentions that the 'base repository' i.e. sanskrit-lexicon/csl-orig and 'head repository' i.e. drdhaval2785/csl-orig differ in case of 2 lines of pe.txt shown below.

4. We want to bring 3 commits already there on sanskrit-lexicon/csl-orig to drdhaval2785/csl-orig first. So, we change the 'base repository' to 'drdhaval2785/csl-orig' and 'head repository' to 'sanskrit-lexicon/csl-orig'. This is a bit tricky. Please see the steps closely.

5. Select 'drdhaval2785/csl-orig' in the 'base repository'
   

6. You will now see a blank kind of screen (because you are comparing drdhaval2785/csl-orig to drdhaval2785/csl-orig i.e. no change would be there)
   

7. Click on 'compare across forks'
   

8. You will see something like this
   

9. Select 'sanskrit-lexicon/csl-orig' inside 'head repository'.
   

10. You will see the three commits which drdhaval2785/csl-orig was behind sanskrit-lexicon/csl-orig. Click on 'Create Pull Request'
    

11. Write some commit message in place 1 (I wrote blah blah). Click on 'Create Pull Request' in place 2.
    

12. Click on 'Merge Pull Request'
    

13. Click on 'Confirm Merge'
    

14. The changes at sanskrit-lexicon/csl-orig are now pulled to drdhaval2785/csl-orig
    

15. Go to https://github.com/drdhaval2785/csl-orig and check. Your fork will not be behind any commit. It will be ahead by some commits.
    

Now your fork is updated.

You can now create a pull request to sanskrit-lexicon/csl-orig (for change in pe.txt) by following steps mentioned in this comment, as usual.

[drdhaval2785]

Update your local files

Because you pulled some changes from sanskrit-lexicon/csl-orig to drdhaval2785/csl-orig, your local files would not have those changes. The changes are still inside github website only. You need to bring those changes to your files on your computer.
Kindly follow the steps mentioned in #31 (comment) to update your local files too.

[AnnaRybakovaT]

Dear Dhaval,
Thanks a lot for your instruction! Now I managed to update the forked repo (inside github website and on my computer).

[funderburkjim]

I managed to update the forked repo

Kudos!