diff --git a/.github/workflows/Docs.yml b/.github/workflows/Docs.yml new file mode 100644 index 00000000..ab8b835a --- /dev/null +++ b/.github/workflows/Docs.yml @@ -0,0 +1,51 @@ +name: Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "src/**" + - "*.toml" + tags: ["*"] + pull_request: + branches: + - main + paths: + - "docs/**" + - "src/**" + - "*.toml" + types: [opened, synchronize, reopened] + +concurrency: + # Skip intermediate builds: always. + # Cancel intermediate builds: only if it is a pull request build. + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }} + +jobs: + docs: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: julia-actions/setup-julia@v1 + with: + version: "1" + - run: | + julia --project=docs -e ' + using Pkg + Pkg.develop(PackageSpec(path=pwd())) + Pkg.instantiate()' + - run: | + julia --project=docs -e ' + using Documenter: DocMeta, doctest + using COPIERTemplate + DocMeta.setdocmeta!(COPIERTemplate, :DocTestSetup, :(using COPIERTemplate); recursive=true) + doctest(COPIERTemplate)' + - run: julia --project=docs docs/make.jl + env: + JULIA_PKG_SERVER: "" + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} diff --git a/.github/workflows/Test.yml b/.github/workflows/Test.yml new file mode 100644 index 00000000..0a6faca7 --- /dev/null +++ b/.github/workflows/Test.yml @@ -0,0 +1,79 @@ +name: Test + +on: + push: + branches: + - main + paths: + - "src/**" + - "test/**" + - "*.toml" + tags: ["*"] + pull_request: + branches: + - main + paths: + - "src/**" + - "test/**" + - "*.toml" + types: [opened, synchronize, reopened] + +concurrency: + # Skip intermediate builds: always. + # Cancel intermediate builds: only if it is a pull request build. + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }} + +jobs: + test: + name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + version: + - "1.6" + - "1" + - "nightly" + os: + - ubuntu-latest + - macOS-latest + # - windows-latest + arch: + - x64 + allow_failure: [false] + include: + - version: "nightly" + os: ubuntu-latest + arch: x64 + allow_failure: true + - version: "nightly" + os: macOS-latest + arch: x64 + allow_failure: true + # - version: "nightly" + # os: windows-latest + # arch: x64 + # allow_failure: true + steps: + - uses: actions/checkout@v3 + - uses: julia-actions/setup-julia@v1 + with: + version: ${{ matrix.version }} + arch: ${{ matrix.arch }} + - uses: actions/cache@v1 + env: + cache-name: cache-artifacts + with: + path: ~/.julia/artifacts + key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }} + restore-keys: | + ${{ runner.os }}-test-${{ env.cache-name }}- + ${{ runner.os }}-test- + ${{ runner.os }}- + - uses: julia-actions/julia-buildpkg@v1 + - uses: julia-actions/julia-runtest@v1 + - uses: julia-actions/julia-processcoverage@v1 + - uses: codecov/codecov-action@v1 + with: + file: lcov.info diff --git a/.gitignore b/.gitignore index b19d550c..9a8db360 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ +.CondaPkg *.jl.*.cov *.jl.cov *.jl.mem -Manifest.toml -docs/build/ *.rej +docs/build/ +Manifest.toml diff --git a/CondaPkg.toml b/CondaPkg.toml new file mode 100644 index 00000000..432fb20b --- /dev/null +++ b/CondaPkg.toml @@ -0,0 +1,2 @@ +[deps] +copier = "" diff --git a/Project.toml b/Project.toml index f7ad5307..3914c785 100644 --- a/Project.toml +++ b/Project.toml @@ -3,5 +3,10 @@ uuid = "5022dd56-1d41-4538-9f4c-b20739ff8283" authors = ["Abel Soares Siqueira and contributors"] version = "0.1.7" +[deps] +CondaPkg = "992eb4ea-22a4-4c89-a5bb-47a3300528ab" +PythonCall = "6099a3de-0909-46bc-b1f4-468b9a2dfc0d" +UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4" + [compat] julia = "1.6" diff --git a/README.md b/README.md index 743df193..3042a0d8 100644 --- a/README.md +++ b/README.md @@ -28,22 +28,27 @@ I have done that in the past, but now I want even less manual intervention. ## How to install -1. Install [copier](https://copier.readthedocs.io). +> **Warning** +> +> There is no Windows support due to an issue with unsupported paths. +> See [Issue #21](https://github.com/abelsiqueira/COPIERTemplate.jl/pull/21). -1. Run copier with this template +1. Install this package, use the module and run `COPIERTemplate.generate(path)`. - ```bash - copier copy https://github.com/abelsiqueira/COPIERTemplate.jl YourPackage.jl - ``` + Alternatively, this can also be installed directly via [copier](https://copier.readthedocs.io), with the command -1. Follow the instructions. In particular you will need a UUID. Your Linux might have `uuidgen` installed, but you can also use Julia: + ```bash + copier copy https://github.com/abelsiqueira/COPIERTemplate.jl YourPackage.jl + ``` - ```bash - using UUIDs - uuid4() - ``` + Follow the instructions. In particular you will need a UUID. Your Linux might have `uuidgen` installed, but you can also use Julia: + + ```bash + using UUIDs + uuid4() + ``` -1. The resulting folder will not be a `git` package yet (to avoid trust issues), so you need to handle that yourself. First, install [`pre-commit`](https://pre-commit.com), and then issue: +2. The resulting folder will not be a `git` package yet (to avoid trust issues), so you need to handle that yourself. First, install [`pre-commit`](https://pre-commit.com), and then issue: ```bash cd YourPackage.jl @@ -57,13 +62,13 @@ I have done that in the past, but now I want even less manual intervention. It is common to have some pre-commit issues due to your package's name length triggering JuliaFormatter. -1. Create a repo on GitHub and push it +3. Create a repo on GitHub and push it ```bash git remote add origin https://github.com/UserName/PackageName.jl ``` -1. Create a `DOCUMENTER_KEY`, which will be used by for documentation purposes. +4. Create a `DOCUMENTER_KEY`, which will be used by for documentation purposes. ```bash pkg> activate --temp @@ -74,7 +79,7 @@ I have done that in the past, but now I want even less manual intervention. Follow the instruction in the terminal. -1. Create a Personal Access Token to be used by the Copier workflow. +5. Create a Personal Access Token to be used by the Copier workflow. 1. Go to . 2. Create a token with "Content", "Pull-request", and "Workflows" permissions. @@ -82,7 +87,7 @@ I have done that in the past, but now I want even less manual intervention. 4. Go to your YOUR_PACKAGE_URL/settings/secrets/actions. 5. Create a "New repository secret" named `COPIER_PAT`. -1. Before releasing, enable Zenodo integration at . +6. Before releasing, enable Zenodo integration at . ## What are all these files? diff --git a/copier.yml b/copier.yml index 9118e426..1a00c714 100644 --- a/copier.yml +++ b/copier.yml @@ -52,6 +52,8 @@ UseCirrusCI: _exclude: - .git + - .github/workflows/Docs.yml + - .github/workflows/Test.yml - CHANGELOG.md - copier.yml - LICENSE diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..341f1ed5 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,10 @@ +# Don't forget to run +# +# pkg> dev .. +# +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +COPIERTemplate = "5022dd56-1d41-4538-9f4c-b20739ff8283" + +[compat] +Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..4eef3614 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,26 @@ +using COPIERTemplate +using Documenter + +DocMeta.setdocmeta!(COPIERTemplate, :DocTestSetup, :(using COPIERTemplate); recursive = true) + +makedocs(; + modules = [COPIERTemplate], + doctest = true, + linkcheck = true, + authors = "Abel Soares Siqueira and contributors", + repo = "https://github.com/abelsiqueira/COPIERTemplate.jl/blob/{commit}{path}#{line}", + sitename = "COPIERTemplate.jl", + format = Documenter.HTML(; + prettyurls = get(ENV, "CI", "false") == "true", + canonical = "https://abelsiqueira.github.io/COPIERTemplate.jl", + assets = ["assets/style.css"], + ), + pages = [ + "Home" => "index.md", + "Contributing" => "contributing.md", + "Dev setup" => "developer.md", + "Reference" => "reference.md", + ], +) + +deploydocs(; repo = "github.com/abelsiqueira/COPIERTemplate.jl", push_preview = true) diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 00000000..6e41c9e5 --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1,26 @@ +# Contributing guidelines + +First of all, thanks for the interest! + +We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc. + +Be polite and respectful. + +## Bug reports and discussions + +If you think you found a bug, feel free to open an [issue](https://github.com/abelsiqueira/COPIERTemplate.jl/issues). +Focused suggestions and requests can also be opened as issues. +Before opening a pull request, start an issue or a discussion on the topic, please. + +## Working on an issue + +If you found an issue that interests you, comment on that issue what your plans are. +If the solution to the issue is clear, you can immediately create a pull request (see below). +Otherwise, say what your proposed solution is and wait for a discussion around it. + +> **tip** +> +> Feel free to ping us after a few days if there are no responses. + +If your solution involves code (or something that requires running the package locally), check the [developer documentation](developer.md). +Otherwise, you can use the GitHub interface directly to create your pull request. diff --git a/docs/src/developer.md b/docs/src/developer.md new file mode 100644 index 00000000..c40ebf0f --- /dev/null +++ b/docs/src/developer.md @@ -0,0 +1,89 @@ +a# Developer documentation + +If you haven't, please read the [Contributing guidelindes](contributing.md) first. + +## Linting and formatting + +Install a plugin on your editor to use [EditorConfig](https://editorconfig.org). +This will ensure that your editor is configured with important formatting settings. + +We use [https://pre-commit.com](https://pre-commit.com) to run the linters and formatters. +In particular, the Julia code is formatted using [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl), so please install it globally first. + +Install `pre-commit` (we recommend using [pipx](https://pypa.github.io/pipx/)): + +```bash +# Install pipx following the link +pipx install pre-commit +``` + +With `pre-commit` installed, activate it as a pre-commit hook: + +```bash +pre-commit install +``` + +To run the linting and formatting manually, enter the command below: + +```bash +pre-commit run -a +``` + +**Now, you can only commit if all the pre-commit tests pass**. + +## First time clone + +1. Fork this repo +2. Clone your repo (this will create a `git remote` called `origin`) +3. Add this repo as a remote `git remote add orgremote https://github.com/abelsiqueira/COPIERTemplate.jl` + +## Working on a new issue + +1. Fetch from the JSO remote and fast-forward your local main + + ```bash + git fetch orgremote + git switch main + git merge --ff-only orgremote/main + ``` + +2. Branch from `main` to address the issue (see below for naming) + + ```bash + git switch -c 42-add-answer-universe + ``` + +3. Push the new local branch to your personal remote repository + + ```bash + git push -u origin 42-add-answer-universe + ``` + +4. Create a pull request to merge your remote branch into the org main. + +### Branch naming + +- If there is an associated issue, add the issue number. +- If there is no associated issue, **and the changes are small**, add a prefix such as "typo", "hotfix", "small-refactor", according to the type of update. +- If the changes are not small and there is no associated issue, then create the issue first, so we can properly discuss the changes. +- Use dash separated imperative wording related to the issue (e.g., `14-add-tests`, `15-fix-model`, `16-remove-obsolete-files`). + +### Commit message + +- Use imperative, present tense (Add feature, Fix bug) +- Have informative titles +- If necessary, add a body with details + +### Before creating a pull request + +- [Advanced] Try to create "atomic git commits" (recommended reading: [The Utopic Git History](https://blog.esciencecenter.nl/the-utopic-git-history-d44b81c09593)). +- Make sure the tests pass. +- Make sure the pre-commit tests pass. +- Fetch any `main` updates from upstream and rebase your branch, if necessary: + + ```bash + git fetch orgremote + git rebase orgremote/main BRANCH_NAME + ``` + +- Then you can open a pull request and work with the reviewer to address any issues diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..e8a005d2 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,7 @@ +```@meta +CurrentModule = COPIERTemplate +``` + +# COPIERTemplate + +Documentation for [COPIERTemplate](https://github.com/abelsiqueira/COPIERTemplate.jl). diff --git a/docs/src/reference.md b/docs/src/reference.md new file mode 100644 index 00000000..3a86a678 --- /dev/null +++ b/docs/src/reference.md @@ -0,0 +1,17 @@ +# Reference + +## Contents + +```@contents +Pages = ["reference.md"] +``` + +## Index + +```@index +Pages = ["reference.md"] +``` + +```@autodocs +Modules = [COPIERTemplate] +``` diff --git a/src/COPIERTemplate.jl b/src/COPIERTemplate.jl new file mode 100644 index 00000000..f5cd77f5 --- /dev/null +++ b/src/COPIERTemplate.jl @@ -0,0 +1,26 @@ +module COPIERTemplate + +using PythonCall, CondaPkg, UUIDs + +function __init__() + CondaPkg.add("copier") +end + +""" + generate(path) + +Runs the `copy` command of [copier](https://github.com/copier-org/copier) with the COPIERTemplate template. +Even though the template is available offline through this template, this uses the github URL to allow updating. + +The `data` argument is a dictionary with answers. +""" +function generate(path, generate_uuid = true; kwargs...) + copier = PythonCall.pyimport("copier") + data = copy(get(kwargs, :data, Dict())) + if generate_uuid + data["PackageUUID"] = string(uuid4()) + end + copier.run_copy("gh:abelsiqueira/COPIERTemplate.jl", path; kwargs..., data = data) +end + +end diff --git a/test/runtests.jl b/test/runtests.jl new file mode 100644 index 00000000..ae292bdb --- /dev/null +++ b/test/runtests.jl @@ -0,0 +1,25 @@ +using COPIERTemplate +using Test + +template_options = Dict( + "PackageName" => "Tmp", + "PackageUUID" => "1234", + "PackageOwner" => "test", + "AuthorName" => "Test", + "AuthorEmail" => "test@me.now", + "JuliaMinVersion" => "1.6", + "License" => "MIT", + "AddMacToCI" => true, + "AddWinToCI" => true, + "RunJuliaNightlyOnCI" => true, + "UseCirrusCI" => true, +) + +@testset "Compare folder generated by this call vs direct copier" begin + tmpdir1 = mktempdir() + tmpdir2 = mktempdir() + + COPIERTemplate.generate(tmpdir1; data = template_options) + bash_args = vcat([["-d"; "$k=$v"] for (k, v) in template_options]...) + run(`copier copy $bash_args https://github.com/abelsiqueira/COPIERTemplate.jl $tmpdir2`) +end