How to contribute (create a pull request) to this repository on Windows (for tensor4all developers only)

Open Windows PowerShell to run commands

Open Windows PowerShell and navigate your working directory. In the following, we assume the working directory is work/tensor4all relative to the user's home directory. In Unix operating systems this corresponds to $HOME/work/tensor4all.

PS C:\path\to\somewhere> cd ~
PS C:\Users\teras> pwd

Path
----
C:\Users\teras


PS C:\Users\teras> mkdir .\work\tensor4all\


    Directory: C:\Users\teras\work


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----         7/20/2024  11:38 AM                tensor4all


PS C:\Users\teras> cd .\work\tensor4all\
PS C:\Users\teras\work\tensor4all> pwd

Path
----
C:\Users\teras\work\tensor4all

Install GitHub CLI

To submit pull requests and make changes to repositories within tensor4all, it's necessary to clone the repository using the SSH protocol. This allows us to push local changes to the remote repository on GitHub. In principle, this involves creating an SSH key and adding the public key to GitHub. GitHub offers the GitHub CLI, known as the gh auth login command, to authenticate with your GitHub account.

We follow this instruction to install gh command.

PS> winget install --id GitHub.cli

Here is a screenshot showing the procedures for installing the GitHub CLI.

As described in this instruction we have to open a new Windows PowerShell session.

Note The Windows installer modifies your PATH. When using Windows Terminal, you will need to open a new window for the changes to take effect.

To confirm that the gh command is installed properly, you can execute the following command:

PS> gh --version
gh version 2.53.0 (2024-07-17)
https://github.com/cli/cli/releases/tag/v2.53.0
PS>

Next, we authenticate with a GitHub host so that we can clone our repositories in tensor4all organization. Run the following command. During the authentication process, you will be prompted to provide additional information.

PS> gh auth login --git-protocol ssh --web
? Generate a new SSH key to add to your GitHub account? Yes # type y if fine
? Enter a passphrase for your new SSH key (Optional): # Just press Enter key is fine
? Title for your SSH key: (GitHub CLI) KeyMyWindowsLaptop # configure as your preference

! First copy your one-time code: <ONE-TIME CODE>
Press Enter to open github.com in your browser... # Here press Enter

Pressing the Enter key will launch the default web browser, which will navigate to a page requesting the input of a one-time code.

Afterward, you should follow the instructions displayed on the GitHub pages

On the Windows PowerShell session we will see the following output:

✓ Authentication complete.
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Uploaded the SSH key to your GitHub account: xxxxxxxxxxxxxxx
✓ Logged in as <Your GitHub Account>
PS>

gh auth status shows the current active account and authentication state on each known GitHub host.

PS> gh auth status
github.com
  ✓ Logged in to github.com account <GitHub Account>
  - Active account: true
  - Git operations protocol: ssh
  - Token: gho_************************************
  - Token scopes: 'admin:public_key', 'gist', 'read:org', 'repo'
PS>

Clone this repository

In the continuation of getting gh command we clone tensor4all/T4AJuliaTutorials repository.

PS> gh repo clone tensor4all/T4AJuliaTutorials
Cloning into 'T4AJuliaTutorials'...
remote: Enumerating objects: 2123, done.
remote: Counting objects: 100% (507/507), done.
remote: Compressing objects: 100% (295/295), done.
remote: Total 2123 (delta 260), reused 380 (delta 201), pack-reused 1616
Receiving objects: 100% (2123/2123), 126.39 MiB | 11.29 MiB/s, done.
Resolving deltas: 100% (946/946), done.
PS C:\Users\teras\work\tensor4all>

Since we have configured to GitHub CLI so that we use SSH protocol by default, this should be equivalent to running the following command:

PS C:\Users\teras\work\tensor4all> git clone git@github.com:tensor4all/T4AJuliaTutorials.git

We can confirm the URL for remote Git repository [email protected]:tensor4all/T4AJuliaTutorials.git

PS C:\Users\teras\work\tensor4all> cd .\T4AJuliaTutorials\
PS C:\Users\teras\work\tensor4all\T4AJuliaTutorials> git remote get-url origin
git@github.com:tensor4all/T4AJuliaTutorials.git
PS C:\Users\teras\work\tensor4all\T4AJuliaTutorials>

It's important to note that the prefix [email protected]: signifies the use of the SSH protocol for pushing changes to remote Git repositories. While the HTTPS protocol allows cloning, it does NOT permit pushing changes. If we use gh repo clone command, we only have to care about the name of repository to clone our desired target repository.

In short gh command is great.

Create a branch

If you're doing some work, you need to come up with a branch name in Git that's appropriate for the work you're doing. For example, if you have a branch named For example, if you wanted to update quantics1d.jl, you would do the following:

PS> git checkout -b update-quantics1d-jl

This will create a branch named update-quantics1d-jl

Commit changes

Configure user.email and user.name

If you commit changes on your machine for the first time, you will get the following error message: Make sure you configure your "user.name" and "user.email" in git.

To resolve this issue, we should configure user.name and user.email. Open Windows PowerShell and run the following commands:

PS> git config --global user.name "YourNameHere"
PS> git config --global user.email "[email protected]"

Please refer to the official GitHub documentation Setting your username in Git to learn more.

Commit changes

If you updated quantics1d.jl, add quantics1d.jl to staging area

PS> git add quantics1d.jl

Then run git commit with message for example:

PS> git commit -m "Update quantics1d.jl"

Push changes to remote repository

Now you have updated and commited changes regarding quantics1d.jl. Let's push the changes to remote repository

PS> git push origin update-quantics1d-jl

This will push local changes to remote repository.

Create a pull request

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request