ports/CommitStyle.md

Policy for commits in Venom ports
============================

This document defines policy for organizing and titling commits for
inclusion in Venom ports.

Glossary
---------

Definition used for the following terms.

##### Repository

Where the spkgbuild resides, it is the penultimate repository in the path of
the port.

Example: `main/foo/spkgbuild`, `main` is the repository

##### Port

Directory inside the repository that contains a build recipe with metadata
(spkgbuild) and auxiliary files (.checksums, .pkgfiles, patches, config, ... ).

The name of the directory and the value of the variable `name` in the
build recipe **must** match.

Example: `main/foo/spkgbuild`, `foo` is the port

##### Commits

Set of changes to files as recorded by git with other metadata like title,
message and an autogenerated ID.

##### Merge Request

Proposal of a set of commits to be merged into a branch of a repository.

This is what maintainers review, and what Continous Integration checks to
guarantee it won't break anything.

In Venom Linux ports terms this is in the `repos` branch of the
repo. 

Organizing
----------

Commits should be split by function and what port they change, one commit
per port changed, and one commit per type of change.

Commits that are related to the same port or are closely related must be
under the same Merge Request.

Commit types
------------

Different sets of changes in a commit award a different type that has a
distinct template, rules and exceptions to follow when organizing and titling.

---

### Upgrade

Increases the value of `version`, and sets the value of `release` to 1.

###### Template

- `$name: upgrade to $version`
  
Example: `foo: upgrade to 5.1.3`

###### Rules

One commit per upgraded port.

### Downgrade

Decreases the value of `version`, and increases the value of `release` by 1 in 
relation to the value of `release` before the last upgrade.

###### Template

- `$name: downgrade to $version`

Example: `foo: downgrade to 1.9.8`

###### Rules

One commit per downgraded port.

---

### Move

Moves an port from one repository to another.

###### Template

- `$name: move to <new repository> from <old repository>`

Example: `foo: move to main from testing`

###### Rules

One commit per moved port.

---

### Rename

Renames an port.

###### Template

- `<new name>: rename from <old name>`

Example: `bar: rename from foo`

###### Rules

One commit per renamed port.

---

### Add

Introduces a new port.

###### Template

- `$name: new port at $version`

Example: `bar: new port at 3.1`

###### Rules

One commit per port introduced.

---

### Remove

Removes an port from ports altogether.

#### Template

- `$name: remove`

Example: `baz: remove`

#### Rules

One commit per removed port.

---

### Rebuilds

Only increasing the value of `release` by 1.

#### Template

- `$name: rebuild <reason-if-exists>`

Example: `foo: rebuild with bar $version`

#### Rules

One commit per rebuilt port.

### Other

Any set of changes not specified above falls under this type.

#### Template

If the commit changes an port:

- `$name: <action>`
- `foo: fix build`

#### Rules

It is **essential** to include reasoning for the changes in the body of the
commit.

Universal Title writing rules
-----------------------------

Applies to all commits, regardless of type.

### Imperative, Present Tense

Use the Present Tense and the Imperative mood

Examples:

- `foo: remove stale patches`
- `bar: patch CVE-YYYY-XXXXX`
- `baz: fix policy violations`

### Lowercase, No dot

Text after the colon must start in lowercase and have no dot at the end.

### Direct, Short

Focus on **what** the commit does and use as few words as possible.

If possible also tell **why**.

Good examples:

- `foo: fix build under gcc-13`
    - `fix build` is **what**
    - `under gcc-10` is **why**
- `foo: disable support for X`
    - `disable support for X` is **what**

They are short and concise, they tell **what** the commit did. If given
the opportunity also tell **why**.

Repository Conventions
=======================

Repository conventions are important in order to ensure every package resemble themselves. 

- Prefer release tarballs over git packages unless there is a sensible reason. Here are some:

       - Every patch is a new release. 
       - There are no releases (luajit now is rolling)
       - Following a development branch.
       - There has been a long time since the latest release, but upstream is far ahead. 

- Always install a package to the `/usr` prefix.

       - All binaries should go to `/usr/bin` or `/usr/sbin` in any cases.
       - All libraries should go to `/usr/lib`. Not exist `/usr/libexec` in Venom Linux.

- All build files on the repository should be a POSIX shell script, and must start with `#!/bin/sh`. 

The next section is about package templates that should be used in order to ensure stylistic consistency. Note that the option configurations shouldn’t be taken literally, they are meant as examples.

### Make
	  #!/bin/sh

    ./configure \
        	--prefix=/usr \
        	--disable-option \
        	--enable-option
    make
    make DESTDIR=$PKG install
	

### Autoconf/Automake
	  #!/bin/sh 

    autoreconf -fi

    ./configure \
        	--prefix=/usr \
        	--disable-option \
        	--enable-option
    make
    make DESTDIR=$PKG install
	

### Meson
The distribution provides a `venom-meson` wrapper script which sets some common options. This is the preferred method.

    #!/bin/sh 

    venom-meson $name-$version build \
        	-Doption=false \
        	-Doption2=true
    meson compile -C build
    DESTDIR=$PKG meson install --no-rebuild -C build
	
    
### Cmake	
    #!/bin/sh 

    cmake -S $name-$version -B build \
   		-DCMAKE_INSTALL_PREFIX=/usr \
   		-DCMAKE_INSTALL_LIBDIR=lib \
   		-DCMAKE_INSTALL_LIBEXECDIR=lib \
		-DCMAKE_BUILD_TYPE=Release \
		-DCMAKE_C_FLAGS_RELEASE="$CFLAGS" \
		-DCMAKE_CXX_FLAGS_RELEASE="$CXXFLAGS" \
		-DOPTION=ON/OFF \
		-Wno-dev 
    cmake --build build
    DESTDIR=$PKG cmake --install build
	
    
### Go
    #!/bin/sh

    cd $name-$version

		export CGO_LDFLAGS="${LDFLAGS}"
  		export CGO_CFLAGS="${CFLAGS}"
		export CGO_CPPFLAGS="${CPPFLAGS}"
		export CGO_CXXFLAGS="${CXXFLAGS}"
		export GOFLAGS="-buildmode=pie -trimpath -mod=readonly -modcacherw -ldflags=-linkmode=external"
		export GOPATH=$SRC/go
		export PATH=$PATH:$GOPATH/bin
    
    go build -o bin/$name *.go
    

### Python (setup)
    #!/bin/sh

    python3 setup.py build
    python3 setup.py install --prefix=/usr --root=$PKG


### Python (pip)
    #!/bin/sh
  
    pip3 install --isolate --root=$PKG 


### Python (build)
    #!/bin/sh
  
    python3 -m build --wheel --skip-dependency-check --no-isolation
    python3 -m installer --destdir=$PKG