# Maintaining Opkg

This document contains policy documentation and helpful references for how this fork of the Opkg project is maintained and released.


----
## Policies

### Version Policy

This fork follows the semantic versioning specification outlined [here](https://semver.org/spec/v2.0.0.html) as SemVer 2.0.

In short...
```
Given a version number MAJOR.MINOR.PATCH, increment the:

    1. MAJOR version when you make incompatible API changes
    2. MINOR version when you add functionality in a backwards compatible manner
    3. PATCH version when you make backwards compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
```

**Public API.** For Opkg, the public API is the `opkg` CLI application; the opkg configuration files; the public API of the libopkg library; and the on-disk structure of OPK/IPK package files, status, and control files.


### Release Policy

This fork's maintainer will create a stable release on a semi-annual basis (in June and December) by tagging the ultimate release commit with a release tag and uploading a canonical archive of the release source to the yocto project's [opkg download mirror](http://downloads.yoctoproject.org/releases/opkg/). For more detailed information, see the "Releasing Opkg" section below.

If there have been no substantial changes to the project source since the prior release, the maintainer might choose to skip that release. This decision should ideally be announced on the mailing list.


----
## Releasing Opkg

### Requirements

To carry out the steps in this section, you must have:
1. **permission** from the Yocto project to act as maintainer (obviously)
	* If you believe it is appropriate for you to be a maintainer, start a discussion on the opkg mailing list (see CONTRIBUTING) and on the Yocto project mailing list <yocto@lists.yoctoproject.org>.

2. a consistent **GPG signing keypair**, for artifact signing.
	* Google around for how to make one.

3. a yocto project (Linux Foundation) **SSH account**, to upload the opkg release information.
	* If you do not have an account, contact Michael Halstead <mhalstead@linuxfoundation.org>.


### Workflow

1. Update the [CHANGELOG](CHANGELOG.md) with a summary of the notable changes since the prior release.

2. Based on the changes, set the version for the release in the `:CMakeLists.txt` file.
	1. Bump the version numbers according to the Version Policy above.
	1. Comment-out the lines which append the ``+git`` suffix to the version.
	1. Commit the results.

3. Create the release artifacts using the `:scripts/make-dist.sh` script.
	```bash
	bash scripts/make-dist.sh -k ${YOUR_GPG_PRIVATE_KEY} HEAD
	```

	The script should create a complete set of release artifacts in a `:dist/` directory.

4. (Optional) Test the dist build in an OpenEmbedded-Core build.

5. Tag and sign the release commit with the version string. Include the changelog for this release in the tag summary.
	```bash
	git tag --sign --local-user=${GPG_KEY_ID} v${VERSION}
	```

6. Uncomment the ``+git`` suffix lines in the ``:CMakeLists.txt`` file, to support next-cycle's development. Commit the results.

7. Push the `:dist/` artifacts to the yocto download server using SSH.
	```bash
	ssh ${USER}@access-vk.yoctoproject.org "mkdir -p ~/opkg; rm -v ~/opkg/*"
	rsync ./dist/* ${USER}@access-vk.yoctoproject.org:~/opkg
	```
	Notify Michael Halstead <mhalstead@linuxfoundation.org> that there is a new opkg release at that path which is ready to be published to the mirror.

8. Publish the release commits and tag to the [Yocto git server](https://git.yoctoproject.org/opkg/).
	```bash
	git push yocto HEAD:master
	git push yocto v${VERSION}
	```

9.  Make an announcement to the opkg mailing list that the new release is available. Include the release notes in the email.

10. Prepare an upgrade commit for the [OE-core opkg recipe](https://git.openembedded.org/openembedded-core/tree/meta/recipes-devtools/opkg). Once the source tar is available on the download mirror, upstream the recipe upgrade with the OE-core mailing list.

	```
	opkg: upgrade to version ${VERSION}

	Opkg ${VERSION} changes:
	<snip from the release log>

	${SIGNOFF}
	```

11. Add the released version to the enum of `versions` in the [opkg project config](https://bugzilla.yoctoproject.org/editversions.cgi?product=opkg) on bugzilla.


----
## Managing Maintainers

When adding new project maintainers, an announcement should be made on the Opkg mailing list, and the community given the opportunity to object for at least a month.

Once all objections are resolved, the lead (or outgoing) maintainer should formalize the new maintainer's role by performing the following actions.

1. Declare the new maintainer in the [`:docs/CONTRIBUTING.md`](/docs/CONTRIBUTING.md) file.

2. If the new maintainer is also the recipe maintainer of the OpenEmbedded Core opkg recipe, they should be declared in the OE-core [`:maintainers.inc`](https://git.openembedded.org/openembedded-core/tree/meta/conf/distro/include/maintainers.inc) file.

3. Request an SSH account for the new maintainer on `access-vk.yoctoproject.org` by opening an email ticket to `helpdesk@yoctoproject.org`.

4. Elevate the new maintainer's mailing list permissions on the [Opkg mailing list](https://lists.yoctoproject.org/g/opkg).

5. Upload the new maintainer's PGP key to [Ubuntu's keyserver](https://keyserver.ubuntu.com).

When removing project maintainers, most of the above items should simply be reversed.
