Skip to content

Latest commit

 

History

History
297 lines (225 loc) · 11.1 KB

CONTRIBUTING.md

File metadata and controls

297 lines (225 loc) · 11.1 KB
Raw

Octave Packages contribution guidelines

This guide explains how to add your Octave package or toolbox to https://gnu-octave.github.io/packages/.

🚀 Quick info

✅ Add your package

🔄 Update your package

🔰 Example package entry

An example package entry packages/pkg-example.yaml (see output):

---
layout: "package"
permalink: "pkg-example/"
description: >-
  Example package to demonstrate the creation process of an Octave package.
  Keep this description brief.  Describe the major features in the first two
  lines (160 characters).

  Multiple lines are allowed.  Each line may have maximal 80 characters.
  Exceptions are URLs.  Paragraphs, blank lines, and line breaks are ignored
  and replaced by spaces.
icon: "https://raw.githubusercontent.com/gnu-octave/pkg-example/main/doc/icon.png"
links:
- icon: "far fa-copyright"
  label: "GPL-3.0-or-later"
  url: "https://github.com/gnu-octave/pkg-example/blob/main/COPYING"
- icon: "fas fa-rss"
  label: "news"
  url: "https://github.com/gnu-octave/pkg-example/releases/"
- icon: "fas fa-code-branch"
  label: "repository"
  url: "https://github.com/gnu-octave/pkg-example/"
- icon: "fas fa-book"
  label: "package documentation"
  url: "https://github.com/gnu-octave/pkg-example/blob/main/README.md"
- icon: "fas fa-bug"
  label: "report a problem"
  url: "https://github.com/gnu-octave/pkg-example/issues"
maintainers:
- name: "Kai T. Ohlhus"
  contact: "k.ohlhus@gmail.com"
- name: "Another Contactless Developer"
  contact:
versions:
- id: "1.1.0"
  date: "2021-04-06"
  sha256: "bff441755f0d68596f2efd027fe637b5b6c52b722ffd6255bdb8a5f34ab4ef2a"
  url: "https://github.com/gnu-octave/pkg-example/archive/1.1.0.tar.gz"
  depends:
  - "octave (>= 4.0.0)"
  - "pkg"
- id: "1.0.0"
  date: "2020-09-02"
  sha256: "6b7e4b6bef5a681cb8026af55c401cee139b088480f0da60143e02ec8880cb51"
  url: "https://github.com/gnu-octave/pkg-example/archive/1.0.0.tar.gz"
  depends:
  - "octave (>= 4.0.0)"
  - "pkg"
- id: "dev"
  date:
  sha256:
  url: "https://github.com/gnu-octave/pkg-example/archive/main.zip"
  depends:
  - "octave (>= 5.2.0)"
  - "pkg"
---

📚 Details

✏️ General specifications

  • For technical reasons, the first and last line --- of the file are fixed and may not be altered.

  • Indent by 2 spaces (no tabs) and leave one space after colon :.

  • All strings must be enclosed with double quotes ". description is an exception using a block style string marked by >-. The description string is > folded (no literal line breaks) and - chopped by the final newline.

📑 Individual field explanations

  • layout: fixed string "package" for technical reasons.

  • permalink: string with the name of the package followed by a slash "/". Must match the file name and must be lower case.

    Note: The prefix "pkg-" is not necessary.

  • description: see example above.

  • icon: URL string to a publicly accessible image. It will be displayed with 50px width in the package index and with 150px with in the individual package page.

  • links: list containing three fields.

    • icon: any free FontAwesome class string is permitted. The icon is part of the hyperlink.

    • label: string of the hyperlink.

    • url: string of the hyperlink.

    You are free to choose any links in any order describing your package best. However, it has proved useful to give some basic information, as seen in the example above:

    • Link to your license or copyright information. For the label use an SPDX string, e.g. "GPL-3.0-or-later".

    • Link to release news.

    • Link to your development repository.

      Note: The star count ⭐ relies on this particular URL. Keep it as short and genuine as possible, e.g. "https://github.com/gnu-octave/pkg-example/", without branch or tree information.

      Only GitLab and GitHub are currently supported.

    • Link to your package documentation or homepage.

    • Link to report a problem.

  • maintainers: list containing two fields.

  • versions: list containing five fields.

    Note: The first version in this list is regarded as recommended for installation. Avoid listing an unstable development version at the first position. It is recommended, not necessary, to sort your releases from the newest (top) to the oldest (bottom).

    • id: unique identifier string for this version, e.g. "1.0.1", "dev", ...

    • date: date string in the format "YYYY-MM-DD" (ISO 8601) or blank if a date does not apply for the release type.

    • sha256: hash string to verify integrity of your package archive or blank if integrity validation is not applicable.

      Tip: The hash string can be obtained on many systems by the sha256sum command:

      # sha256sum pkg-example-1.0.0.tar.gz

6b7e4b6bef5a681cb8026af55c401cee139b088480f0da60143e02ec8880cb51  pkg-example-1.0.0.tar.gz

      or using Octave

      >> urlwrite ("https://github.com/gnu-octave/pkg-example/archive/1.0.0.tar.gz", "pkg-example-1.0.0.tar.gz");
>> hash ("sha256", fileread ("pkg-example-1.0.0.tar.gz"))
ans = 6b7e4b6bef5a681cb8026af55c401cee139b088480f0da60143e02ec8880cb51

    • url: URL string of the release archive (tarball or zip file).

      Tip: For package development it can be handy to use the automatic archive generation feature of many source code hosting services, such as GitHub, GitLab, ...

      See the example package entry above for installing the current "main" branch of the package development repository without creating a release.

    • depends: list of dependency strings.

      A dependency string looks like "pkg" or "octave (>= 5.2.0)".

      The dependency "pkg" with any or no version marks this package as installable by the Octave pkg-tool.

      A dependency starts with the name (e.g. "pkg" or "octave"), optionally followed by the version in round brackets (parentheses) separated by a single space. The optional version starts with an operator (e.g. >=) separated by a space to the dependent version 5.2.0.

      Permitted names are "pkg", "octave", and any other package.

      Note: Refrain from adding system libraries here, for example. The used package tool might not be able to resolve the dependency and makes this package "uninstallable".

      Permitted operators are documented in the Octave manual "DESCRIPTION"-file "Depends" section.

    • ubuntu2204: list of Ubuntu 22.04 (LTS) dependency strings.

      A dependency string looks like "libopenblas-dev". The corresponding Ubuntu package must be available at https://packages.ubuntu.com/focal/libopenblas-dev, for example.

      The Ubuntu package dependencies are installed during the automatic GitHub Actions review via the default apt-get install-mechanism. It is not necessary to list packages available in the Octave Docker image. Try to keep the list as short as possible.

    • fedora<xxx>: list of Fedora xxx dependency strings.

      Add a fedora40 list item for Fedora 40 and add a fedora41 list item for Fedora 41, for example.

      A dependency string looks like "libzstd". The corresponding Fedora package must be available at https://repology.org/project/libzstd/versions, for example.

      To install Fedora package dependencies on your local machine, run dnf install-command.