diff --git a/Makefile b/Makefile index 35ce7d6..6300cfa 100644 --- a/Makefile +++ b/Makefile @@ -23,11 +23,12 @@ GIT ?= git REUSE ?= reuse RM ?= rm INSTALL ?= install +NPM ?= npm SASS ?= ./node_modules/.bin/sass STYLELINT ?= ./node_modules/.bin/stylelint SCDOC ?= scdoc -REQUIRED_TOOLS := $(GO) $(GIT) $(SASS) $(SCDOC) +REQUIRED_TOOLS := $(GO) $(GIT) $(SASS) $(SCDOC) $(NPM) GO_MIN_VERSION := 1.24 GOBUILD_FLAGS := -trimpath \ diff --git a/README.md b/README.md index 23104ac..fa5d5c3 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ First install the dependencies: - Go 1.24 or above. - make. +- npm. - [scdoc](https://git.sr.ht/~sircmpwn/scdoc). Clone the repository, switch to the latest stable tag, then compile, and @@ -43,6 +44,7 @@ install: git clone 'https://github.com/cipherdothost/pkgdex.git' cd 'pkgdex' git checkout 'v1.0.0' +npm install make sudo make install ``` @@ -56,7 +58,8 @@ sudo make install ## Contributing Anyone can help make **pkgdex** better. Check out [the contribution -guidelines](CONTRIBUTING.md) for more information. +guidelines](CONTRIBUTING.md) and [the development +instructions](docs/development.md) for more information. --- diff --git a/REUSE.toml b/REUSE.toml index cf9d734..576226c 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -17,6 +17,7 @@ path = [ "LICENSE-3rdparty.csv", "config/apparmor/usr.local.bin.pkgdexctl", "config/config.example.json", + "config/dev-config.example.json", "config/nginx/pkg.example.com", "config/systemd/pkgdex.service", "internal/config/testdata/*.json", diff --git a/config/dev-config.example.json b/config/dev-config.example.json new file mode 100644 index 0000000..5b22d1a --- /dev/null +++ b/config/dev-config.example.json @@ -0,0 +1,61 @@ +{ + "service": { + "name": "Pkgdex", + "description": "A curated index of Go packages. Engineered by Cipher Host.", + "contact": "support@example.com", + "homepage": "https://localhost:8080", + "baseURL": "localhost:8080", + "packagesPerPage": 2, + "seo": { + "title": "Cipher Host's Go Package Index", + "description": "A curated collection of professional-grade tools to enhance your Go projects. Browse and discover Cipher Host's carefully engineered Go packages and modules." + } + }, + "server": { + "address": ":8080", + "pid": "/path/to/pkgdex/repository/clone/.dev/pkgdex.pid", + "readTimeout": "5s", + "writeTimeout": "10s", + "idleTimeout": "30s" + }, + "database": { + "path": "/path/to/pkgdex/repository/clone/.dev/pkgdex.db", + "indexPath": "/path/to/pkgdex/repository/clone/.dev/index" + }, + "packages": [ + { + "name": "credential-go", + "description": "A simple interface for retrieving secrets from systemd's credential management system.", + "version": "1.0.0", + "branch": "trunk", + "repository": "https://git.sr.ht/~jamesponddotco/credential-go", + "license": "MIT", + "usage": "
 1package main\n 2\n 3import (\n 4\t"fmt"\n 5\t"log"\n 6\n 7\t"git.sr.ht/~jamesponddotco/credential-go"\n 8)\n 9\n10func main() {\n11\t// Open the credential store with your application's name as the prefix.\n12\tstore, err := credential.Open("myapp")\n13\tif err != nil {\n14\t\tlog.Fatal(err)\n15\t}\n16\n17\t// Retrieve a secret from the store.\n18\tsecret, err := store.Get("database-password")\n19\tif err != nil {\n20\t\tlog.Fatal(err)\n21\t}\n22\n23\t// Print the secret or do something else with it.\n24\tfmt.Println("Database password:", secret)\n25}\n
" + }, + { + "name": "xstd-go", + "description": "Small collection of extensions to Go's standard library.", + "version": "0.12.1", + "branch": "trunk", + "repository": "https://git.sr.ht/~jamesponddotco/xstd-go", + "license": "MIT" + }, + { + "name": "gitignore-go", + "description": "Simple Go parser for .gitignore files.", + "version": "1.0.1", + "branch": "trunk", + "repository": "https://git.sr.ht/~jamesponddotco/gitignore-go", + "license": "MIT" + }, + { + "name": "llmctx", + "description": "CLI tool that converts the content of a directory into context for LLMs.", + "version": "1.0.1", + "branch": "trunk", + "repository": "https://git.sr.ht/~jamesponddotco/llmctx", + "license": "GPL-2.0", + "hidden": true + } + ] +} diff --git a/docs/README.md b/docs/README.md index 1d79374..ea2c5a3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,3 +12,5 @@ SPDX-License-Identifier: CC0-1.0 **pkgdex** yourself. - [Using the service](using.md): How to use the service once it is up and running. +- [Developing the service](development.md): How to develop and + contribute code to **pkgdex**. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..7816791 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,229 @@ + + +# Development + +This document provides technical guidance for developers who want to +contribute code to **pkgdex**. It complements the +[../CONTRIBUTING.md](../CONTRIBUTING.md) file by focusing specifically +on the technical aspects of development. + +Before you begin, please review the +[../CONTRIBUTING.md](../CONTRIBUTING.md) file to understand the overall +contribution guidelines and our code of conduct. + +## Table of Contents + +1. [Development environment](#development-environment-setup) +2. [Building and Testing](#building-and-testing) +3. [Contribution Workflow](#contribution-workflow) +4. [Coding Standards](#coding-standards) +5. [Documentation](#documentation) +6. [License Compliance](#license-compliance) + +## Development Environment + +### Prerequisites + +- Go 1.24 or above +- Node/NPM +- make +- scdoc + +### Setting up your environment + +1. Fork the repository on GitHub. + +2. Clone your fork locally: +```bash +git clone 'https://github.com/YOUR-USERNAME/pkgdex.git' +cd 'pkgdex' +``` + +3. Create a development configuration file: +```bash +mkdir -p '.dev' +cp 'config/dev-config.example.json' '.dev/config.json' +``` + +4. Edit the `.dev/config.json` file to set appropriate development + values. You'll want to edit the following fields: + + - `server.pid` + - `database.path` + - `database.indexPath` + +You may also want to edit the following fields: + + - `service.homepage` + - `service.baseURL` + - `server.address` + +### Creating a self-signed certificate for development + +Since **pkgdex** requires TLS, you'll need to generate a self-signed +certificate for local development: + +```bash +openssl req -x509 -newkey rsa:4096 -keyout '.dev/pkgdex-tlskey' -out '.dev/pkgdex-tlscertificate' -days 365 -nodes -subj '/CN=localhost' +``` + +## Building and Testing + +### Building the project + +To build the project locally, run: + +```bash +npm install +make +``` + +This will compile the binary to `build/pkgdexctl`. + +For development, it's best to use the `development` target with your +development configuration in `.dev`: + +```bash +make development +``` + +By default, this will start the service on `https://localhost:8080`, but +you can change this in the `.dev/config.json` file by modifying the +`server.address` field. You'll need to accept the self-signed +certificate warning. + +> [!NOTE] +> If you modify the server address, you may also want to modify the +> `service.homepage` and `service.baseURL` fields. + +### Running tests + +To run the test suite: + +```bash +make test +``` + +For test output with coverage information: + +```bash +make test/coverage +``` + +## Contribution Workflow + +As said before, review the [../CONTRIBUTING.md](../CONTRIBUTING.md) file +to understand the overall contribution guidelines and our code of +conduct. + +### Creating a feature or fix + +1. Ensure there's an issue for your work: + - Check [existing + issues](https://github.com/cipherdothost/pkgdex/issues) first. + - If none exists, create one clearly describing the bug or feature. + +2. Create a new branch for your work in your fork: +```bash +git checkout -b 'feature/your-feature-name' +# or +git checkout -b 'fix/issue-description' +``` + +3. Make your changes, following the coding standards. + +4. Write tests for your changes. + +5. Update documentation if necessary. + +6. Update the `Unreleased` section of the + [../CHANGELOG.md](../CHANGELOG.md) file. + +### Submitting pull requests + +1. Push your branch to your fork: +```bash +git push origin 'feature/your-feature-name' +``` + +2. Create a pull request against the `trunk` branch of the main + repository. + +3. In your PR description: + - Clearly describe the changes. + - Reference the issue it resolves. + - Note any breaking changes or migration steps. + +4. Wait for code review feedback and address any comments. + +## Coding Standards + +### Go code style + +We like to follow both the Uber and Google Go coding standards, with a +preference for the Uber one when they conflict with each other, and we +expect your contribution to do the same. + +- [Uber style guide](https://github.com/uber-go/guide/blob/master/style.md). +- [Google style guide](https://google.github.io/styleguide/go/) + +### Dependencies + +As mentioned in the [../CONTRIBUTING.md](../CONTRIBUTING.md) file, avoid +adding new dependencies unless absolutely necessary. + +If you need to add a new dependency: + +1. Ensure it's well-maintained and widely used. +2. Check its license for compatibility. +3. Update the [../LICENSE-3rdparty.csv](../LICENSE-3rdparty.csv) file. +4. Run `make tidy` to update the `go.mod` and `go.sum` files. + +## Documentation + +### Code documentation + +- Add godoc comments to all types, functions, and methods, including + non-exported ones. +- Comments should explain the why behind the code, not just the what. +- Put the most important information first in the comment. Aim to make + the first sentence a clear, concise summary. + Focus on the intent and purpose of each part of the code. +- Use complete sentences, proper capitalization and punctuation in + comments. + +### Project documentation + +Project documentation is stored in the `docs/` directory: + +- `hosting.md`: Instructions for deploying the service. +- `config.md`: Configuration reference. +- `using.md`: Usage instructions. +- `development.md`: Development instructions. + +When updating features or APIs, make corresponding updates to the +documentation. If adding new configuration options, update `config.md` +accordingly. + +## License Compliance + +Remember that all code must comply with [the REUSE +specification](https://reuse.software/spec-3.3/). The default license is +[EUPL-1.2](../LICENSE.md). + +Ensure each new file needs the appropriate license header. You can use +the `reuse` tool to help with this: + +```bash +pipx install reuse +make lint/licenses +``` + +--- + +Thank you for contributing to **pkgdex**! Your efforts help make this +project better for everyone.