diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml new file mode 100644 index 00000000..bee44f1a --- /dev/null +++ b/.JuliaFormatter.toml @@ -0,0 +1,7 @@ +annotate_untyped_fields_with_any = false +indent = 2 +margin = 100 +normalize_line_endings = "unix" +remove_extra_newlines = true +whitespace_ops_in_indices = true +whitespace_typedefs = true diff --git a/.copier-answers.yml b/.copier-answers.yml new file mode 100644 index 00000000..93efb62f --- /dev/null +++ b/.copier-answers.yml @@ -0,0 +1,14 @@ +# Changes here will be overwritten by Copier +AddMacToCI: true +AddWinToCI: false +AuthorEmail: abel.s.siqueira@gmail.com +AuthorName: Abel Soares Siqueira +JuliaMinVersion: '1.6' +License: MPL-2.0 +PackageName: COPIERTemplate +PackageOwner: abelsiqueira +PackageUUID: 5022dd56-1d41-4538-9f4c-b20739ff8283 +RunJuliaNightlyOnCI: false +UseCirrusCI: false +_commit: v0.1.7 +_src_path: https://github.com/abelsiqueira/COPIERTemplate.jl diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..9f5c55fc --- /dev/null +++ b/.editorconfig @@ -0,0 +1,10 @@ +# https://editorconfig.org +root = true + +[*] +end_of_line = lf +insert_final_newline = true +charset = utf-8 +indent_size = 2 +indent_style = space +trim_trailing_whitespace = true diff --git a/.github/workflows/CompatHelper.yml b/.github/workflows/CompatHelper.yml new file mode 100644 index 00000000..7825cfe7 --- /dev/null +++ b/.github/workflows/CompatHelper.yml @@ -0,0 +1,49 @@ +# CompatHelper v3.5.0 +name: CompatHelper + +on: + schedule: + - cron: 0 0 * * * + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +jobs: + CompatHelper: + runs-on: ubuntu-latest + steps: + - name: Check if Julia is already available in the PATH + id: julia_in_path + run: which julia + continue-on-error: true + - name: Install Julia, but only if it is not already available in the PATH + uses: julia-actions/setup-julia@v1 + with: + version: "1" + arch: ${{ runner.arch }} + if: steps.julia_in_path.outcome != 'success' + - name: "Add the General registry via Git" + run: | + import Pkg + ENV["JULIA_PKG_SERVER"] = "" + Pkg.Registry.add("General") + shell: julia --color=yes {0} + - name: "Install CompatHelper" + run: | + import Pkg + name = "CompatHelper" + uuid = "aa819f21-2bde-4658-8897-bab36330d9b7" + version = "3" + Pkg.add(; name, uuid, version) + shell: julia --color=yes {0} + - name: "Run CompatHelper" + run: | + import CompatHelper + CompatHelper.main() + shell: julia --color=yes {0} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }} + # COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }} diff --git a/.github/workflows/Copier.yml b/.github/workflows/Copier.yml new file mode 100644 index 00000000..2ecd8792 --- /dev/null +++ b/.github/workflows/Copier.yml @@ -0,0 +1,52 @@ +name: Copier Update + +on: + schedule: + - cron: 0 7 1/7 * * + workflow_dispatch: + +jobs: + Copier: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.COPIER_PAT }} + - uses: julia-actions/setup-julia@v1 + with: + version: "1" + - name: Use Julia cache + uses: julia-actions/cache@v1 + - name: Install JuliaFormatter.jl + run: julia -e 'using Pkg; pkg"add JuliaFormatter"' + - name: Setup Python + uses: actions/setup-python@v4 + - name: Check for update in the template + run: | + pip install copier + copier update -A -o rej + echo -e "Automated changed by Copier.yml workflow\n" > /tmp/body.md + echo -e 'Rejected changes (if any):\n```diff\n' >> /tmp/body.md + find . -name "*.rej" | xargs cat >> /tmp/body.md + find . -name "*.rej" | xargs rm -f + echo -e '```' >> /tmp/body.md + git diff + - name: Run pre-commit to run the formatters + run: | + pip install pre-commit + pre-commit run -a || true # Ignore pre-commit errors + - name: Create Pull Request + id: cpr + uses: peter-evans/create-pull-request@v5 + with: + token: ${{ secrets.COPIER_PAT }} + commit-message: ":robot: COPIERTemplate.jl update" + title: "[AUTO] COPIERTemplate.jl update" + body-path: /tmp/body.md + branch: auto-copier-template-update + delete-branch: true + labels: configuration, automated pr, no changelog + - name: Check outputs + run: | + echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}" + echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}" 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/Lint.yml b/.github/workflows/Lint.yml new file mode 100644 index 00000000..c9f779b6 --- /dev/null +++ b/.github/workflows/Lint.yml @@ -0,0 +1,36 @@ +name: Lint + +on: + push: + branches: + - main + tags: ["*"] + pull_request: + +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: + lint: + name: Linting + runs-on: ubuntu-latest + steps: + - name: Clone + uses: actions/checkout@v3 + - name: Setup Julia + uses: julia-actions/setup-julia@v1 + with: + version: "1" + - name: Use Julia cache + uses: julia-actions/cache@v1 + - name: Install JuliaFormatter.jl + run: julia -e 'using Pkg; pkg"add JuliaFormatter"' + - name: Setup Python + uses: actions/setup-python@v4 + - name: Install pre-commit + run: pip install pre-commit + - name: Run pre-commit + run: SKIP=no-commit-to-branch pre-commit run -a diff --git a/.github/workflows/TagBot.yml b/.github/workflows/TagBot.yml new file mode 100644 index 00000000..dab9b0b6 --- /dev/null +++ b/.github/workflows/TagBot.yml @@ -0,0 +1,37 @@ +name: TagBot + +on: + issue_comment: + types: + - created + workflow_dispatch: + inputs: + lookback: + type: number + default: 3 + +permissions: + actions: read + checks: read + contents: write + deployments: read + issues: read + discussions: read + packages: read + pages: read + pull-requests: read + repository-projects: read + security-events: read + statuses: read + +jobs: + TagBot: + if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot' + runs-on: ubuntu-latest + steps: + - uses: JuliaRegistries/TagBot@v1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + # Edit the following line to reflect the actual name of the GitHub Secret containing your private key + ssh: ${{ secrets.DOCUMENTER_KEY }} + # ssh: ${{ secrets.NAME_OF_MY_SSH_PRIVATE_KEY_SECRET }} diff --git a/.github/workflows/Test.yml b/.github/workflows/Test.yml new file mode 100644 index 00000000..3235a9ee --- /dev/null +++ b/.github/workflows/Test.yml @@ -0,0 +1,67 @@ +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] + + 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 new file mode 100644 index 00000000..b19d550c --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +*.jl.*.cov +*.jl.cov +*.jl.mem +Manifest.toml +docs/build/ +*.rej diff --git a/.markdown-link-config.json b/.markdown-link-config.json new file mode 100644 index 00000000..de14e9ec --- /dev/null +++ b/.markdown-link-config.json @@ -0,0 +1,7 @@ +{ + "ignorePatterns": [ + { + "pattern": "@ref" + } + ] +} diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..8bf958ad --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,13 @@ +{ + "MD007": { + "indent": 2, + "start_indented": false + }, + "MD013": { + "line_length": 1000, + "tables": false + }, + "MD033": false, + "MD041": false, + "default": true +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..49f1c39c --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,55 @@ +repos: + - repo: local + hooks: + # Prevent committing .rej files + - id: forbidden-files + name: forbidden files + entry: found Copier update rejection files; review them and remove them + language: fail + files: "\\.rej$" + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: check-json + - id: check-toml + - id: check-yaml + - id: end-of-file-fixer + - id: file-contents-sorter + files: .JuliaFormatter.toml + args: [--unique] + - id: mixed-line-ending + args: [--fix=lf] + - id: no-commit-to-branch + - id: pretty-format-json + args: [--autofix, --indent=2] + - id: trailing-whitespace + - id: check-merge-conflict + args: [--assume-in-merge] + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.37.0 + hooks: + - id: markdownlint-fix + - repo: https://github.com/citation-file-format/cffconvert + rev: 054bda51dbe278b3e86f27c890e3f3ac877d616c + hooks: + - id: validate-cff + - repo: https://github.com/pre-commit/mirrors-prettier + rev: "v3.0.3" # Use the sha or tag you want to point at + hooks: + - id: prettier + types_or: [yaml, json] + exclude: ".copier-answers.yml" + - repo: https://github.com/adrienverge/yamllint + rev: v1.32.0 + hooks: + - id: yamllint + - repo: https://github.com/domluna/JuliaFormatter.jl + rev: v1.0.36 + hooks: + - id: julia-formatter + - repo: https://github.com/tcort/markdown-link-check + rev: v3.11.2 + hooks: + - id: markdown-link-check + args: + - --config=.markdown-link-config.json diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 00000000..5e16e5fb --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,2 @@ +rules: + indentation: { spaces: 2 } diff --git a/README.md b/README.md index 743df193..18645f5c 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Lint workflow Status](https://github.com/abelsiqueira/COPIERTemplate.jl/actions/workflows/Lint.yml/badge.svg?branch=main)](https://github.com/abelsiqueira/COPIERTemplate.jl/actions/workflows/Lint.yml?query=branch%3Amain) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8350577.svg)](https://doi.org/10.5281/zenodo.8350577) -This is a [copier](https://copier.readthedocs.io) template/skeleton for Julia packages. +This is a [copier](https://copier.readthedocs.io) template/skeleton for Julia packages (see folder [template](template)). - It is opinionated but allows options - Can be used in existing package (thanks for copier) @@ -146,5 +146,6 @@ The select a few workflows, with a strong possibility of expanding in the future The following are users and examples of repos using this template, or other templates based on it. Feel free to create a pull request to add your repo. +- This package itself uses the template. - [COPIERTemplateExample.jl](https://github.com/abelsiqueira/COPIERTemplateExample.jl) - [JSOTemplate.jl](https://github.com/JuliaSmoothOptimizers/JSOTemplate.jl) 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..09c990b3 --- /dev/null +++ b/docs/src/developer.md @@ -0,0 +1,89 @@ +# 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..54c0bf1e --- /dev/null +++ b/src/COPIERTemplate.jl @@ -0,0 +1,5 @@ +module COPIERTemplate + +# Write your package code here. + +end diff --git a/test/Project.toml b/test/Project.toml new file mode 100644 index 00000000..0c363327 --- /dev/null +++ b/test/Project.toml @@ -0,0 +1,2 @@ +[deps] +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" diff --git a/test/runtests.jl b/test/runtests.jl new file mode 100644 index 00000000..77df0a6a --- /dev/null +++ b/test/runtests.jl @@ -0,0 +1,6 @@ +using COPIERTemplate +using Test + +@testset "COPIERTemplate.jl" begin + # Write your tests here. +end