Develop a local version of a registered package and submit changes as a pull request

General Usage
1

I’ve been working through how one would go about making changes to a registered Julia package and submit the changes as a pull request. I haven’t found one source that explains the whole process, so I thought I’d share what I’ve come up with here. Let me know if anything seems wrong or if there are better ways to do this!

Also, I did find a nice PR to the Pkg.jl repo that would add a lot of this to the Pkg docs, though the approach is slightly different from what I have below.

You can use the following procedure to make local changes to a registered Julia package and submit a pull request. The Example.jl package is used as an example.

  1. Fork the package on GitHub.

  2. Clone your fork to a local directory of your choice:

$ git clone https://github.com/YOUR-USERNAME/Example.jl.git`.

Note that the origin for this repo is your forked repo:

$ git remote -v
origin	https://github.com/YOUR-USERNAME/Example.jl (fetch)
origin	https://github.com/YOUR-USERNAME/Example.jl (push)
  1. Set the original GitHub repo as the upstream repo:
$ git remote add upstream https://github.com/JuliaLang/Example.jl

Note that upstream is just a label for the URL of the original repo. Instead of calling it upstream you could call it something else like original. Now that we’ve added the upstream repo, our local repo is aware of two remote repos (origin and upstream):

$ git remote -v
origin	https://github.com/YOUR-USERNAME/Example.jl.git (fetch)
origin	https://github.com/YOUR-USERNAME/Example.jl.git (push)
upstream	https://github.com/JuliaLang/Example.jl (fetch)
upstream	https://github.com/JuliaLang/Example.jl (push)
  1. Now you can keep your local repo in sync with the upstream repo by using git pull:
$ git pull upstream
  1. In the Julia REPL package mode (entered by typing ]), put your local repo into develop mode, which tells the package manager to track the directory containing your local repo:
(v1.1) pkg> develop /home/cbieganek/projects/Example.jl
 Resolving package versions...
  Updating `~/.julia/environments/v1.1/Project.toml`
  [7876af07] ↑ Example v0.5.1 ⇒ v0.5.1+ [`~/projects/Example.jl`]
  Updating `~/.julia/environments/v1.1/Manifest.toml`
  [7876af07] ↑ Example v0.5.1 ⇒ v0.5.1+ [`~/projects/Example.jl`]

We can see that the package manager is now tracking the directory containing our local repo:

(v1.1) pkg> status Example
    Status `~/.julia/environments/v1.1/Project.toml`
  [7876af07] Example v0.5.1+ [`~/projects/Example.jl`]

so if we do using Example in a Julia session, we will see any changes we’ve made to Example.jl.

  1. Create a branch in your local repo and commit your changes to that branch, and then push your changes to your fork on GitHub.
  2. Use GitHub to submit a pull request from your fork to the original repository.
  3. If you wish, you can tell the package manager to return to using the registered version of Example.jl:
(v1.1) pkg> free Example
 Resolving package versions...
  Updating `~/.julia/environments/v1.1/Project.toml`
  [7876af07] ↓ Example v0.5.1+ [`~/projects/Example.jl`] ⇒ v0.5.1
  Updating `~/.julia/environments/v1.1/Manifest.toml`
  [7876af07] ↓ Example v0.5.1+ [`~/projects/Example.jl`] ⇒ v0.5.1

(v1.1) pkg> status Example
    Status `~/.julia/environments/v1.1/Project.toml`
  [7876af07] Example v0.5.1

So now the package manager is no longer tracking changes to the directory with your local repo.

13 Likes
2

A clarification on Step 4:
It seems that git will typically require you to designate which branch you are pulling from upstream. So, if you want to sync with the upstream master branch, you can do the following:

$ git checkout master  # Checkout your local master branch
$ git pull upstream master  # Pull contents of the upstream master branch
1 Like