diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 5057640..9f119f9 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-11T11:02:00","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-13T11:45:53","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/10-full-guide/index.html b/dev/10-full-guide/index.html index 80946cc..fa5894c 100644 --- a/dev/10-full-guide/index.html +++ b/dev/10-full-guide/index.html @@ -13,12 +13,12 @@ git add . git commit -m "First commit" pre-commit install # Future commits can't be directly to main unless you use -n
Now, create a new repository on GitHub and push your code. We won't give you details on how to do this, but you can check The Turing Way.
After that, jump on to Setting up your package.
To apply the template to an existing package, you can do the following:
This assumes that you already use git on that package and the your working directory is clean. It will fail otherwise.
julia> using BestieTemplate
-julia> BestieTemplate.apply("full/path/to/YourPackage.jl")
This command will look around your project path and try to guess some of the answers. Currently, we guess:
PackageName
and PackageUUID
from the name
and uuid
fields in Project.toml
,Authors
from the authors
field in Project.toml
,PackageOwner
from the repo
in docs/make.jl
,JuliaMinVersion
from the compat
section in Project.toml
,Indentation
from the indent
field in .JuliaFormatter.toml
.You will be asked whether to overwrite existing files or not. Since you are using git
, you can try it out and reset if you don't like the result.
If you don't like the result, or want to override the answers, you can run the apply
function with additional arguments, for instance:
julia> data = Dict("Authors" => "Bob <bob@bob.br>")
-julia> BestieTemplate.apply("full/path/to/YourPackage.jl", data)
Alternatively, you can also tell Bestie to not guess:
julia> BestieTemplate.apply("full/path/to/YourPackage.jl"; guess = false)
See the full docstring for BestieTemplate.apply
for more information.
You will most likely have conflicts when you apply the template. Whenever a conflict appears, you will need to decide on whether to accept or reject the new changes. Unfortunately, they are not shown to you when the conflict appears, so the best solution is to just accept all of them and then fix the conflicts using git
.
Don't just add the changes blindly, because some of your files can and will be overwritten.
We really can't avoid some conflicts, and although some file can be skipped if existing (such as CITATION.cff), some can't. For instance, README.md will most likely be wrong when you apply the template, but the badges (for instance), need to be included in your project. This means that README.md cannot be skipped, and you will have to accept the overwrite and manually fix your README.md.
You might most likely see changes in the formatting. So if you have are a formatter, it might be best to run it before reviewing the changes. If you have chosen the "Recommended" answers, or explicitly chose to add pre-commit
, then you should use it now (see below).
If you need some help with undoing some of these changes, I recommend using a graphical interface. After the template is applied and you are happy with the conflict resolution, enable pre-commit and push your code.
git add .
+julia> BestieTemplate.apply("full/path/to/YourPackage.jl")
This command will look around your project path and try to guess some of the answers. Currently, we guess:
PackageName
and PackageUUID
from the name
and uuid
fields in Project.toml
,Authors
from the authors
field in Project.toml
,PackageOwner
from the repo
in docs/make.jl
,JuliaMinVersion
from the compat
section in Project.toml
,Indentation
from the indent
field in .JuliaFormatter.toml
.You will be asked whether to overwrite existing files or not. Since you are using git
, you can try it out and reset if you don't like the result. So we recommend overwriting at this point.
If you don't like the result, or want to override the answers, you can run the apply
function with additional arguments, for instance:
julia> data = Dict("Authors" => "Bob <bob@bob.br>")
+julia> BestieTemplate.apply("full/path/to/YourPackage.jl", data)
Alternatively, you can also tell Bestie to not guess:
julia> BestieTemplate.apply("full/path/to/YourPackage.jl"; guess = false)
See the full docstring for BestieTemplate.apply
for more information.
Don't just add the changes blindly, because some of your files can and will be overwritten.
We really can't avoid some conflicts, and although some file can be skipped if existing (such as CITATION.cff), some can't. For instance, README.md will most likely be wrong when you apply the template, but the badges (for instance), need to be included in your project. This means that README.md cannot be skipped, and you will have to accept the overwrite and manually fix your README.md.
You might most likely see changes in the formatting. So if you have a formatter, it might be best to run it before reviewing the changes. If you have chosen the "Recommended" answers, or explicitly chose to add pre-commit
, then you should use it now (see below).
If you need some help with undoing some of these changes, I recommend using a graphical interface for git. After the template is applied and you are happy with the conflict resolution, enable pre-commit and push your code.
git add .
pre-commit run -a # Try to fix possible pre-commit issues (failures are expected)
pre-commit install # All commits will run pre-commit now
git add .
-git commit -m "Apply BestieTemplate vx.y.z"
Push your code to GitHub and head to Setting up your package for information on what to do next.
Now, go to Setting up your package to check what you still need to configure for your package.
To update the package, simply call
julia> BestieTemplate.update()
You will be asked the relevant questions of the package as if you had applied it. The big differences are:
You can change your previous answers. In other words, if you though something was not mature enough in the past, but you are more confident in that now, you can adopt it now. This works even if the template was not updated itself.
As with the first application, you need to run pre-commit run -a
to fix the unavoidable linting and formatting issues. Check the modifications in the relevant linter and formatting files, if you changed them manually, before doing it, though.
pre-commit run -a
The underlying package copier
will use git
to apply the differences and it will overwrite whatever files it finds in the way. Since git
is mandatory, the changes will be left for you to review.
I repeat, the changes will be left for you to review. Don't just add them blindly, because some of your modifications can and will be overwritten.
If you need some help with undoing some of these changes, I recommend using a graphical interface.
There are various steps to setting up your package on GitHub. Some are important now, and some will be relevant when you try to make your first release.
If you haven't yet, create a repo on GitHub and push your code to it.
The actions will run and you will see errors in the documentation and linting. Do not despair.
Go to your package setting on Github and find the "Actions" tab, the "General" link. On that page, find the "Workflow permissions" and change the selection to "Read and write permissions", and enable "Allow GitHub Actions can create and approve pull requests". This will allow the documentation workflow to work for development.
Go to the Actions page, click the failing Docs workflow and click on "re-run all jobs". It should pass now.
Now, go to your package setting on GitHub and find the "Pages" link. You should see an option to set the Source to "Deploy from a branch", and select the branch to be "gh-pages" and to deploy from the "/ (root)".
After circa 1 minute, you can check that the documentation was built properly.
At this point, you should have passing workflows.
This section is only relevant when making your first release, but it might be better to get it out of the way now.
You need to set a DOCUMENTER_KEY
to build the documentation from the tags automatically when using TagBot (which we do by default). Do the following:
pkg> activate --temp
+git commit -m "Apply BestieTemplate vx.y.z"
Push your code to GitHub and head to Setting up your package for information on what to do next.
Now, go to Setting up your package to check what you still need to configure for your package.
To update the package, simply call
julia> BestieTemplate.update()
You will be asked the relevant questions of the package as if you had applied it. The big differences are:
You can change your previous answers. In other words, if you though something was not mature enough in the past, but you are more confident in that now, you can adopt it now. This works even if the template was not updated itself.
As with the first application, you need to run pre-commit run -a
to fix the unavoidable linting and formatting issues. Check the modifications in the relevant linter and formatting files, if you changed them manually, before doing it, though.
pre-commit run -a
You will possibly have conflicts when you apply the template - i.e., updates to the template that conflicts with changes that you've made to the package. Whenever a conflict appears, you will need to decide on whether to accept or reject the new changes. Fix the conflicts using git
.
The underlying package copier
will use git
to apply the differences and it will overwrite whatever files it finds in the way. Since git
is mandatory, the changes will be left for you to review.
I repeat, the changes will be left for you to review. Don't just add them blindly, because some of your modifications can and will be overwritten.
If you need some help with undoing some of these changes, I recommend using a graphical interface to git.
There are various steps to setting up your package on GitHub. Some are important now, and some will be relevant when you try to make your first release.
If you haven't yet, create a repo on GitHub and push your code to it.
The actions will run and you will see errors in the documentation and linting. Do not despair.
Go to your package setting on Github and find the "Actions" tab, the "General" link. On that page, find the "Workflow permissions" and change the selection to "Read and write permissions", and enable "Allow GitHub Actions can create and approve pull requests". This will allow the documentation workflow to work for development.
Go to the Actions page, click the failing Docs workflow and click on "re-run all jobs". It should pass now.
Now, go to your package setting on GitHub and find the "Pages" link. You should see an option to set the Source to "Deploy from a branch", and select the branch to be "gh-pages" and to deploy from the "/ (root)".
After circa 1 minute, you can check that the documentation was built properly.
At this point, you should have passing workflows.
This section is only relevant when making your first release, but it might be better to get it out of the way now.
You need to set a DOCUMENTER_KEY
to build the documentation from the tags automatically when using TagBot (which we do by default). Do the following:
pkg> activate --temp
pkg> add DocumenterTools
julia> using DocumenterTools
-julia> DocumenterTools.genkeys(user="UserName", repo="PackageName.jl")
Follow the instruction in the terminal.
If you don't have a Codecov account, go to https://codecov.io and create one now. After creating an account and logging in, you will see your main page with a list of your packages. Select the one that you are creating, it will open a configuration page.
On the configuration page, select "Using GitHub Actions" as your CI. The first step in the list given you the CODECOV_TOKEN
. Click on the "repository secret" link on that page. It should lead you to the GitHub settings > secrets and variables > actions, under a "New secret" screen. Write CODECOV_TOKEN
on the "Name" field and paste the token that you see on codecov on the "Secret" field. Click "Add secret".
Step 2 is not necessary because it is already present in the template.
The next time that the tests are run, the coverage page will be updated, and the badge will be fixed.
This option is not selected by default because it is a work in progress. If you want to use it, you have to pass the key "AddCopierCI" => true
to the data
argument of generate
or apply
, or select "Ask me" when deciding how to answer the optional questions.
You can reapply the template in the future. This is normally a manual job, specially because normally there are conflicts. That being said, we are experimenting with having a workflow that automatically checks whether there are updates to the template and reapplies it. A Pull Request is created with the result.
This is optional, and in development, so you might want to delete the workflow instead.
If you decide to use, here are the steps to set it up:
YOUR_PACKAGE_URL/settings/secrets/actions
.COPIER_PAT
.Update your CITATION.cff
file with correct information. You can use cffinit to generate it easily.
Before releasing, enable Zenodo integration at https://zenodo.org/account/settings/github/ to automatically generate a deposition of your package, i.e., archive a version on Zenodo and generate a DOI.
Enable GitHub discussions.
When you are ready to make your first release, enable the Julia Registrator bot. Make sure that you haven't skipped these sections:
Settings
This document was generated with Documenter.jl version 1.7.0 on Wednesday 11 September 2024. Using Julia version 1.10.5.