From da6ca05abf04b26995cb5bec923dce7fda886d31 Mon Sep 17 00:00:00 2001 From: Matthijs Arnoldus Date: Tue, 30 Apr 2024 11:55:49 +0200 Subject: [PATCH] First commit --- .JuliaFormatter.toml | 7 + .copier-answers.yml | 14 ++ .editorconfig | 10 ++ .github/workflows/CompatHelper.yml | 49 +++++++ .github/workflows/Copier.yml | 52 ++++++++ .github/workflows/Docs.yml | 51 ++++++++ .github/workflows/Lint.yml | 36 ++++++ .github/workflows/TagBot.yml | 37 ++++++ .github/workflows/Test.yml | 66 ++++++++++ .gitignore | 6 + .markdown-link-config.json | 7 + .markdownlint.json | 13 ++ .pre-commit-config.yaml | 55 ++++++++ .yamllint.yml | 2 + CITATION.cff | 10 ++ LICENSE | 201 +++++++++++++++++++++++++++++ Project.toml | 7 + README.md | 25 ++++ docs/Project.toml | 10 ++ docs/make.jl | 26 ++++ docs/src/contributing.md | 26 ++++ docs/src/developer.md | 95 ++++++++++++++ docs/src/index.md | 7 + docs/src/reference.md | 17 +++ src/MGA.jl | 5 + test/Project.toml | 2 + test/runtests.jl | 6 + 27 files changed, 842 insertions(+) create mode 100644 .JuliaFormatter.toml create mode 100644 .copier-answers.yml create mode 100644 .editorconfig create mode 100644 .github/workflows/CompatHelper.yml create mode 100644 .github/workflows/Copier.yml create mode 100644 .github/workflows/Docs.yml create mode 100644 .github/workflows/Lint.yml create mode 100644 .github/workflows/TagBot.yml create mode 100644 .github/workflows/Test.yml create mode 100644 .gitignore create mode 100644 .markdown-link-config.json create mode 100644 .markdownlint.json create mode 100644 .pre-commit-config.yaml create mode 100644 .yamllint.yml create mode 100644 CITATION.cff create mode 100644 LICENSE create mode 100644 Project.toml create mode 100644 README.md create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/contributing.md create mode 100644 docs/src/developer.md create mode 100644 docs/src/index.md create mode 100644 docs/src/reference.md create mode 100644 src/MGA.jl create mode 100644 test/Project.toml create mode 100644 test/runtests.jl diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml new file mode 100644 index 0000000..bee44f1 --- /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 0000000..72ed896 --- /dev/null +++ b/.copier-answers.yml @@ -0,0 +1,14 @@ +# Changes here will be overwritten by Copier +AddMacToCI: true +AddWinToCI: true +AuthorEmail: m.arnoldus-1@tudelft.nl +AuthorName: Matthijs Arnoldus +JuliaMinVersion: '1.6' +License: Apache-2.0 +PackageName: MGA +PackageOwner: TulipaEnergy +PackageUUID: a88418a5-8dc5-4f1c-8a3e-d5a75ec49c70 +RunJuliaNightlyOnCI: false +UseCirrusCI: false +_commit: v0.2.5 +_src_path: https://github.com/abelsiqueira/COPIERTemplate.jl diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9f5c55f --- /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 0000000..7825cfe --- /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 0000000..2ecd879 --- /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 0000000..196f3ff --- /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 MGA + DocMeta.setdocmeta!(MGA, :DocTestSetup, :(using MGA); recursive=true) + doctest(MGA)' + - 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 0000000..c9f779b --- /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 0000000..dab9b0b --- /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 0000000..49a5fe0 --- /dev/null +++ b/.github/workflows/Test.yml @@ -0,0 +1,66 @@ +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" + 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 0000000..b19d550 --- /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 0000000..de14e9e --- /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 0000000..8bf958a --- /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 0000000..49f1c39 --- /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 0000000..5e16e5f --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,2 @@ +rules: + indentation: { spaces: 2 } diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..19e5e85 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,10 @@ +# Go to https://citation-file-format.github.io/cff-initializer-javascript/#/ to finish this +cff-version: 1.2.0 +title: MGA.jl +message: >- + If you use this software, please cite it using the + metadata from this file. +type: software +authors: + - given-names: Matthijs Arnoldus + email: m.arnoldus-1@tudelft.nl diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..aa7acc7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2023 [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/Project.toml b/Project.toml new file mode 100644 index 0000000..426c73d --- /dev/null +++ b/Project.toml @@ -0,0 +1,7 @@ +name = "MGA" +uuid = "a88418a5-8dc5-4f1c-8a3e-d5a75ec49c70" +authors = ["Matthijs Arnoldus and contributors"] +version = "0.1.0" + +[compat] +julia = "1.6" diff --git a/README.md b/README.md new file mode 100644 index 0000000..3dd9e3a --- /dev/null +++ b/README.md @@ -0,0 +1,25 @@ +# MGA + + + +[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://TulipaEnergy.github.io/MGA.jl/stable) +[![In development documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://TulipaEnergy.github.io/MGA.jl/dev) +[![Build Status](https://github.com/TulipaEnergy/MGA.jl/workflows/Test/badge.svg)](https://github.com/TulipaEnergy/MGA.jl/actions) +[![Test workflow status](https://github.com/TulipaEnergy/MGA.jl/actions/workflows/Test.yml/badge.svg?branch=main)](https://github.com/TulipaEnergy/MGA.jl/actions/workflows/Test.yml?query=branch%3Amain) +[![Lint workflow Status](https://github.com/TulipaEnergy/MGA.jl/actions/workflows/Lint.yml/badge.svg?branch=main)](https://github.com/TulipaEnergy/MGA.jl/actions/workflows/Lint.yml?query=branch%3Amain) +[![Docs workflow Status](https://github.com/TulipaEnergy/MGA.jl/actions/workflows/Docs.yml/badge.svg?branch=main)](https://github.com/TulipaEnergy/MGA.jl/actions/workflows/Docs.yml?query=branch%3Amain) + +[![Coverage](https://codecov.io/gh/TulipaEnergy/MGA.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/TulipaEnergy/MGA.jl) +[![DOI](https://zenodo.org/badge/DOI/FIXME)](https://doi.org/FIXME) + +## How to Cite + +If you use MGA.jl in your work, please cite using the reference given in [CITATION.cff](https://github.com/TulipaEnergy/MGA.jl/blob/main/CITATION.cff). + +## Contributing + +If you want to make contributions of any kind, please first that a look into our [contributing guide directly on GitHub](docs/src/contributing.md) or the [contributing page on the website](https://TulipaEnergy.github.io/MGA.jl/dev/contributing/). + +--- + +This repo was created with the [COPIERTemplate.jl](https://github.com/abelsiqueira/COPIERTemplate.jl) package. diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..d1c07c7 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,10 @@ +# Don't forget to run +# +# pkg> dev .. +# +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +MGA = "a88418a5-8dc5-4f1c-8a3e-d5a75ec49c70" + +[compat] +Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..c1fca53 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,26 @@ +using MGA +using Documenter + +DocMeta.setdocmeta!(MGA, :DocTestSetup, :(using MGA); recursive = true) + +makedocs(; + modules = [MGA], + doctest = true, + linkcheck = true, + authors = "Matthijs Arnoldus and contributors", + repo = "https://github.com/TulipaEnergy/MGA.jl/blob/{commit}{path}#{line}", + sitename = "MGA.jl", + format = Documenter.HTML(; + prettyurls = get(ENV, "CI", "false") == "true", + canonical = "https://TulipaEnergy.github.io/MGA.jl", + assets = ["assets/style.css"], + ), + pages = [ + "Home" => "index.md", + "Contributing" => "contributing.md", + "Dev setup" => "developer.md", + "Reference" => "reference.md", + ], +) + +deploydocs(; repo = "github.com/TulipaEnergy/MGA.jl", push_preview = true) diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 0000000..e02c4c6 --- /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/TulipaEnergy/MGA.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 0000000..ea2d5cf --- /dev/null +++ b/docs/src/developer.md @@ -0,0 +1,95 @@ +# Developer documentation + +If you haven't, please read the [Contributing guidelines](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. + +To install `pre-commit`, we recommend using [pipx](https://pipx.pypa.io) as follows: + +```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 + +If this is the first time you work with this repository, follow the instructions below to clone the repository. + +1. Fork this repo +2. Clone your repo (this will create a `git remote` called `origin`) +3. Add this repo as a remote: + + ```bash + git remote add orgremote https://github.com/TulipaEnergy/MGA.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 or present tense, for instance: *Add feature* or *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 0000000..fac20cd --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,7 @@ +```@meta +CurrentModule = MGA +``` + +# MGA + +Documentation for [MGA](https://github.com/TulipaEnergy/MGA.jl). diff --git a/docs/src/reference.md b/docs/src/reference.md new file mode 100644 index 0000000..de777df --- /dev/null +++ b/docs/src/reference.md @@ -0,0 +1,17 @@ +# Reference + +## Contents + +```@contents +Pages = ["reference.md"] +``` + +## Index + +```@index +Pages = ["reference.md"] +``` + +```@autodocs +Modules = [MGA] +``` diff --git a/src/MGA.jl b/src/MGA.jl new file mode 100644 index 0000000..6992817 --- /dev/null +++ b/src/MGA.jl @@ -0,0 +1,5 @@ +module MGA + +# Write your package code here. + +end diff --git a/test/Project.toml b/test/Project.toml new file mode 100644 index 0000000..0c36332 --- /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 0000000..d719f41 --- /dev/null +++ b/test/runtests.jl @@ -0,0 +1,6 @@ +using MGA +using Test + +@testset "MGA.jl" begin + # Write your tests here. +end