# \[Ann\]\[Tutorial\] How-to develop a Julia package from scratch

**URL:** <https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227>\
**Category:** Community\
**Tags:** tutorials\
**Created:** [December 22, 2020, 1:28pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227 "2020-12-22T13:28:02Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [December 22, 2020, 1:28pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/1 "2020-12-22T13:28:02Z")

</div>

As part of my efforts to update the [Julia Concise Tutorial](https://syl1.gitbook.io/julia-language-a-concise-tutorial/), I completely rewritten the chapter dedicated to “[How to develop a Julia Package](https://syl1.gitbook.io/julia-language-a-concise-tutorial/language-core/11-developing-julia-packages)”.

Yes, sure we have the “[Creating Packages](https://julialang.github.io/Pkg.jl/v1/creating-packages/)” section in the documentation… but that’s only about the package generation (and testing).

I have long had the feeling that something was missing about the _complete_ typical workflow required to develop a Julia package… from choosing the name, setting up a GitHub repository, generate the package, put everything together, add automatic tests, add the configurations for the documentation, deal with github actions as CompactHelper and TagBot and finally register the package.

For each step I propose in the tutorial the steps required for a “typical” package installation, but I link to the relevant documentation for users that need more options.

Following [the tutorial](https://syl1.gitbook.io/julia-language-a-concise-tutorial/language-core/11-developing-julia-packages) a user with little experience should be able to develop a simple package on the lines of [MyAwesomePackage](https://github.com/sylvaticus/MyAwesomePackage.jl).

(PS… I am particularly proud of my `plusTwo()` function… too often the examples we make to explain some topic are unnecessarily complex)

---

<div class="post-metadata">

**Author:** ![DoktorMike](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/doktormike/32/2736_2.png) [@DoktorMike](https://discourse.julialang.org/u/DoktorMike)\
**Post date:** [December 22, 2020, 2:06pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/2 "2020-12-22T14:06:30Z")

</div>

I think this is extremely useful. A guide that shows a way from a to z in setting up and developing a package is really needed. I think all the bits and pieces are already documented all around but this consolidated view is really great. I’ll be sending this along to budding julia package developers in my network. 🙏🏻

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [December 24, 2020, 7:16am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/3 "2020-12-24T07:16:35Z")

</div>

I think that it is best to use a package template generator, eg

> **[GitHub - JuliaCI/PkgTemplates.jl: Create new Julia packages, the easy way](https://github.com/JuliaCI/PkgTemplates.jl)**
>
> Create new Julia packages, the easy way. Contribute to JuliaCI/PkgTemplates.jl development by creating an account on GitHub.

> **[GitHub - tpapp/PkgSkeleton.jl: Generate Julia package skeletons using a...](https://github.com/tpapp/PkgSkeleton.jl)**
>
> Generate Julia package skeletons using a simple template system - GitHub - tpapp/PkgSkeleton.jl: Generate Julia package skeletons using a simple template system

Various aspects of the tooling (CI, Tagbot, …) change from time to time, detailed guides tend to become outdated quickly.

---

<div class="post-metadata">

**Author:** ![rafael.guerra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rafael.guerra/32/216610_2.png) [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)\
**Post date:** [December 24, 2020, 8:00am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/4 "2020-12-24T08:00:09Z")

</div>

There is also [DrWatson.jl](https://github.com/JuliaDynamics/DrWatson.jl)

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [December 25, 2020, 8:54pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/5 "2020-12-25T20:54:54Z")

</div>

…ny…

For the same reasons package generation tools get outdated too, in my case when I needed it a few months ago for example they didn’t work because of some changes… and if that is the case you are “dead”… With a good tutorial (that by no chance I claim mine to be) instead, you should get at least a feeling of how things work and you may able to adapt to the changed situation… And then, contribute back to a markdown page is easier than contribute to correct the tool…

Still, package generation tools are great if you need to create many packages …

---

<div class="post-metadata">

**Author:** ![felix](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/felix/32/604_2.png) [@felix](https://discourse.julialang.org/u/felix)\
**Post date:** [December 27, 2020, 1:36pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/6 "2020-12-27T13:36:11Z")

</div>

This tutorial is very helpful, thank you! I definitely fit the bill of “a user with little experience”

* * *

It was not always clear to me which directories I should be in. Here are my thoughts/questions as I was going through

> We cd to a directory where we want the new package to appear as a subfolder, enter the Julia prompt and type `(@v1.X) pkg> generate MyAwesomePackage`

Ok, so … I start making the package on my desktop for now. Looks like `Pkg.generate` also put a file in the `.julia/dev` folder though

> We first “activate” the new `MyAwesomePackage` folder with `(@v1.X) pkg> activate(FULL_PATH/MyAwesomePackage)`

I guess `FULL_PATH` refers to my desktop, not the `.julia/dev` copy

> Let leave Julia for now and go to the local repository with a terminal

Which one? On my desktop or in `.julia/dev`?

> Once we have the package in GitHub, we can add it to our Julia local installation with `(@v1.X) pkg> add https://github.com/sylvaticus/MyAwesomePackage.jl.git` and `(@v1.X) pkg> dev MyAwesomePackage`. The package should now reside to `[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage`

What does it mean, reside? Do I edit this copy, or the one that I have git linked to on my Desktop? What’s the relationship between the two?

* * *

I personally would also have benefited from another section, maybe “Developing” somewhere between “Creating” and “Documenting”, which showed the typical workflow of changing the package. Starting from a blank slate, I guess I pull it from github, then make changes, commit and push back to github. (Maybe more of a github tutorial point?)

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [December 28, 2020, 10:24am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/7 "2020-12-28T10:24:22Z")

</div>

Hello, if you are on your Desktop, enter Julia and type `] generate Foo`, than `Foo` shoudn’t have any entry in `.julia/dev`, just one folder in `Desktop/Foo`.

I added a few lines on continuous development of the package:

With out package in `[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/` we can continue to develop it, commit the changes and push them to GitHub (behind the scenes, the `add` and `dev` Julia package commands did actually cloned the GitHub repository to `.julia/dev/MyAwesomePackage/`, so we can use directly git commands on that directory, like `git commit -a -m "Commit message"` or `git push`).

#### Further development of the package

In the most basic situation, we would keep the `main` branch locally, continue our development, and when we consider it is “time” to release a new version we just change the `version` information in the package `Project.toml`, we commit/push the new “version” and we raise the `@JuliaRegistrator register` “command” again in GitHub.  
This will have the effect to register the new version in the Julia official Register, with TagBot creating an equivalent version on the GitHub repository.

---

<div class="post-metadata">

**Author:** ![Gregstrq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gregstrq/32/20620_2.png) [@Gregstrq](https://discourse.julialang.org/u/Gregstrq)\
**Post date:** [January 9, 2021, 12:16am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/8 "2021-01-09T00:16:15Z")

</div>

I followed the guide and created manually the directory “.github/workflow” and the files “ci.yml” and “CompatHelper.yml”. However, after I pushed it to github, none of the badges I added to README.md is working.

Was I supposed to add the actions in Github and not locally?

---

<div class="post-metadata">

**Author:** ![Gregstrq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gregstrq/32/20620_2.png) [@Gregstrq](https://discourse.julialang.org/u/Gregstrq)\
**Post date:** [January 9, 2021, 12:41am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/9 "2021-01-09T00:41:57Z")

</div>

Ok. I deleted the “.github/workflow” directory that I manually created and set up the workflows directly from Github. Now it works.

If the actions are really supposed to be added from Github, may be you should emphasize it in your guide.  
Also, you might want to add how to setup Documenter SSH KEY.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [January 9, 2021, 8:07am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/10 "2021-01-09T08:07:43Z")

</div>

> [@Gregstrq](#):
>
> If the actions are really supposed to be added from Github, may be you should emphasize it in your guide.  
> Also, you might want to add how to setup Documenter SSH KEY.

Hello, no, you can but you don’t need to set up the actions in GitHub, adding the workflow files in the repository should suffix.  
Did you `git add [file]` before making the commit?  
After you set the workflow file locally, commit it and push it to the repository, you should be able to check for any error into the “Actions” tab of your repository in GitHub.

Concerning the setup of the Documenter SSH key, this is explained in the tutorial, but I guess in a too much concise way.  
I will add to that, thank you.

---

<div class="post-metadata">

**Author:** ![rikh](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rikh/32/204104_2.png) [@rikh](https://discourse.julialang.org/u/rikh)\
**Post date:** [January 9, 2021, 9:08am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/11 "2021-01-09T09:08:20Z")

</div>

Maybe the CI contained branches: - master, while new GitHub repositories now default to a brach called main instead of master.

---

<div class="post-metadata">

**Author:** ![Gregstrq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gregstrq/32/20620_2.png) [@Gregstrq](https://discourse.julialang.org/u/Gregstrq)\
**Post date:** [January 9, 2021, 2:16pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/12 "2021-01-09T14:16:35Z")

</div>

No, this change was accounted for in the guide. Moreover, I just copied to github the content of the same files I tried to push from my local machine. May there are some special git read-write rights that need to be set up correctly?

---

<div class="post-metadata">

**Author:** ![Gregstrq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gregstrq/32/20620_2.png) [@Gregstrq](https://discourse.julialang.org/u/Gregstrq)\
**Post date:** [January 9, 2021, 2:21pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/13 "2021-01-09T14:21:03Z")

</div>

> [@sylvaticus](#):
>
> Did you `git add [file]` before making the commit?

I did. I saw the workflow folder with files on Github after the push. Nevertheless, thank you for your response.

I have another question related to the topic of package development. Is it possible to update the docs of tagged version without changing the tag?

---

<div class="post-metadata">

**Author:** ![rikh](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rikh/32/204104_2.png) [@rikh](https://discourse.julialang.org/u/rikh)\
**Post date:** [January 9, 2021, 3:20pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/14 "2021-01-09T15:20:34Z")

</div>

I’ve never had that problem before because normal rights are fine. Other things I can think of are that you forked a repository and didn’t click on “I understand the consequences, enable Actions” or didn’t put the file at the exact correct location.

When the `yml` file is located correctly, GitHub will let you know if the syntax is false, except when the job just doesn’t run as I suggested in my previous comment. If you really want to debug this, please send a link to your GitHub project and the failing commit.

---

<div class="post-metadata">

**Author:** ![Gregstrq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gregstrq/32/20620_2.png) [@Gregstrq](https://discourse.julialang.org/u/Gregstrq)\
**Post date:** [January 9, 2021, 3:26pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/15 "2021-01-09T15:26:25Z")

</div>

> [@rikh](#):
>
> If you really want to debug this,

I think I do not really want to do it. In the end, I made it working, which is fine with me.  
I appreciate your responses, hope you are not irritated that I decided not to push this forward.

---

<div class="post-metadata">

**Author:** ![rikh](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rikh/32/204104_2.png) [@rikh](https://discourse.julialang.org/u/rikh)\
**Post date:** [January 9, 2021, 3:35pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/16 "2021-01-09T15:35:14Z")

</div>

Oh, I assumed you did. Okay, no worries. 👍

---

<div class="post-metadata">

**Author:** ![Eugeleo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eugeleo/32/6440_2.png) [@Eugeleo](https://discourse.julialang.org/u/Eugeleo)\
**Post date:** [November 4, 2021, 5:03pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/17 "2021-11-04T17:03:12Z")

</div>

Encountered the same problem; the correct directory is `.github/workflows/...`, not `.github/workflow/...`. Once I changed this, it started working.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [November 5, 2021, 6:49am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/18 "2021-11-05T06:49:14Z")

</div>

Corrected, thanks. In these cases the best would be to make a pull request directly in the tutorial repository.

---

<div class="post-metadata">

**Author:** ![Eugeleo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eugeleo/32/6440_2.png) [@Eugeleo](https://discourse.julialang.org/u/Eugeleo)\
**Post date:** [November 5, 2021, 7:13am UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/19 "2021-11-05T07:13:35Z")

</div>

I would have gotten to it eventually; I realized what the fix is mid-work on a project, lieterally minutes before I wrote that comment.

---

<div class="post-metadata">

**Author:** ![braamvandyk](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/braamvandyk/32/5086_2.png) [@braamvandyk](https://discourse.julialang.org/u/braamvandyk)\
**Post date:** [March 13, 2022, 6:24pm UTC](https://discourse.julialang.org/t/ann-tutorial-how-to-develop-a-julia-package-from-scratch/52227/20 "2022-03-13T18:24:22Z")

</div>

I realize this is a long dead thread, but I only recently found it.

I need to express my thanks for the excellent section on registering packages. I made some fixes to the one and only package I ever registered and then discovered that nothing I thought I new about registering a package was still relevant. This tutorial was a gift, wrapped in gold!

Thanks a million!