diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 2f8dc28d..4579c168 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-24T09:44:40","documenter_version":"1.5.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-25T08:10:39","documenter_version":"1.5.0"}} \ No newline at end of file diff --git a/dev/10-full-guide/index.html b/dev/10-full-guide/index.html index 8657a464..4138cc5f 100644 --- a/dev/10-full-guide/index.html +++ b/dev/10-full-guide/index.html @@ -20,4 +20,4 @@ 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
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.5.0 on Wednesday 24 July 2024. Using Julia version 1.10.4.