You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A vast majority of Julia packages are hosted on [GitHub](https://github.com/) (although less common, other options like [GitLab](https://gitlab.com/) are also possible).
12
+
GitHub is a platform for collaborative software development, based on the version control system [Git](https://git-scm.com/).
13
+
If you are unfamiliar with these technologies, check out the [GitHub documentation](https://docs.github.com/en/get-started/quickstart).
11
14
12
-
## Code quality
15
+
The first step is therefore [creating](https://github.com/new) an empty GitHub repository.
16
+
You should try to follow [package naming guidelines](https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-guidelines) and add a ".jl" extension at the end, like so: "MyAwesomePackage.jl".
17
+
Do not insert any files like `README.md`, `.gitignore` or `LICENSE.md`, this will be done for you in the next step.
Indeed, we can leverage [PkgTemplates.jl](https://github.com/JuliaCI/PkgTemplates.jl) to automate package creation (like `]generate` from Pkg.jl but on steroids).
20
+
The following code gives you a basic file structure to start with:
You already know that the `src` subfolder contains your source code, but you might wonder what the `test` subfolder is for.
42
+
Its purpose is [unit testing](https://docs.julialang.org/en/v1/stdlib/Test/): automatically checking that your code behaves the way you want it to.
43
+
For instance, if you write your own square root function, you may want to test that it gives the correct results for positive numbers, and errors for negative numbers.
44
+
These tests belong in `test/runtests.jl`, and they may look somewhat like this:
45
+
46
+
```>sqrt
47
+
using Test
48
+
49
+
@test sqrt(4) ≈ 2
50
+
51
+
@testset "Invalid inputs" begin
52
+
@test_throws DomainError sqrt(-1)
53
+
@test_throws MethodError sqrt("abc")
54
+
end
55
+
```
56
+
57
+
Unit testing may seem rather naive, or even superfluous, but as your code grows more complex, it becomes easier to break something without noticing.
58
+
Testing each part separately will increase the reliability of the software you write.
59
+
60
+
If your package requires [test-specific dependencies](https://pkgdocs.julialang.org/v1/creating-packages/#Adding-tests-to-the-package), you can use [TestEnv.jl](https://github.com/JuliaTesting/TestEnv.jl) to activate the test environment with all necessary packages.
61
+
62
+
We list a few advanced testing utilities:
63
+
64
+
*[ReferenceTests.jl](https://github.com/JuliaTesting/ReferenceTests.jl) allows you to compare function outputs with reference files
65
+
*[ReTest.jl](https://github.com/JuliaTesting/ReTest.jl) lets you define tests next to the source code, and control their execution more precisely
66
+
*[TestItemRunner.jl](https://github.com/julia-vscode/TestItemRunner.jl) leverages the testing interface of VSCode
67
+
68
+
## Style
69
+
70
+
To make your code easy to read, it is essential to follow a consistent set of guidelines.
71
+
The official [style guide](https://docs.julialang.org/en/v1/manual/style-guide/) is very short, so most people use third party style guides like [BlueStyle](https://github.com/invenia/BlueStyle) or [SciMLStyle](https://github.com/SciML/SciMLStyle).
72
+
73
+
[JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) is an automated formatter for Julia files.
74
+
It can help you enforce the style guide of your choice if you add a file `.JuliaFormatter.toml` at the root of your repository, containing a single line like
75
+
76
+
```toml
77
+
style = "blue"
78
+
```
79
+
80
+
Then, the current directory will be formatted in the BlueStyle whenever you call
81
+
82
+
```julia-repl
83
+
julia> using JuliaFormatter
84
+
85
+
julia> format(".");
86
+
```
87
+
88
+
This functionality is even [integrated with VSCode](https://www.julia-vscode.org/docs/stable/userguide/formatter/).
The most useful aspect of PkgTemplates.jl is that it automatically generates workflows for [GitHub Actions](https://docs.github.com/en/actions/quickstart).
107
+
These are stored as YAML files in `.github/workflows`, with a slightly convoluted syntax that you don't need to fully understand.
108
+
For instance, the file `CI.yml` contains instructions that execute the tests of your package for each pull request, tag or push to the `main` branch.
109
+
This is done on a GitHub server and should theoretically cost you money, but your GitHub repository is public, you get an unlimited workflow budget for free.
110
+
111
+
The other default workflows are less relevant for new users, but we still mention them:
112
+
113
+
*[CompatHelper.jl](https://github.com/JuliaRegistries/CompatHelper.jl) monitors your dependencies and their versions.
114
+
*[TagBot](https://github.com/JuliaRegistries/TagBot) helps you manage package releases.
0 commit comments