amsterdam/CONTRIBUTING.md

Contribution Guidelines for Amsterdam

Introduction

This document explains how to contribute changes to the Amsterdam project.

Development Location

While you may have found this project on GitHub or another site, the "source of truth" for the project will always reside on the Erbosoft code hosting site. This is to ensure long-term independence from platforms controlled by third parties; the mirrors to GitHub and/or other sites are for visibility.

Serious contributors should contact Amy Bowersox for access.

AI Contribution Policy

As per our Code of Conduct, AI contributions are acceptable, but the submitting contributor must:

• Fully understand the contribution.
• Be able to explain design and implementation decisions without the use of AI.
• Accept responsibility for maintenance and correctness.

Contributors should indicate AI-generated content in issue and pull request descriptions and comments, specifying which model was used.

Do not use AI to reply to questions about your issue or pull request. The questions are for you, the human, not an AI model.

All project contributions must be submitted by identifiable human participants who accept full responsibility for their content. Automated agents, bots, or autonomous AI systems may not independently submit issues, pull requests, or other contributions.

Project maintainers retain full discretion to close pull requests and issues that appear to be low-quality AI-generated content. While we welcome new contributors, we want to see those that will engage constructively with the review process, rather than deferring to AI.

Building Amsterdam

From the root of the source tree, just run go build to build the amsterdam executable.

To regenerate the tailwind.css file (located in ui/static/css), you will need the Tailwind CSS command-line executable. Download it from the Tailwind GitHub and install it as tailwindcss in your PATH. Then run go generate to regenerate the CSS file before you run go build to build the executable.

Contribution Workflow

1. Open an issue describing the problem or proposed feature.
2. Discuss the design with maintainers.
3. Submit a pull request referencing the issue.
4. Participate in code review.

Versioning

Amsterdam employs semantic versioning, with version numbers in the "major.minor.bugfix" format. Please see the linked specification for further details.

Git Branching

Amsterdam employs the GitHub Flow style of branch management.

One thing to remember: when working on a feature branch, and seeking to merge new changes from main into your branch, never use git merge, but always use git rebase to rebase your feature branch off the tip of main. The rule to remember is, changes flowing "inward" from feature branches to main use git merge, but changes flowing "outward" from main to feature branches use git rebase.

Dependencies

Dependencies are managed using Go Modules. You can find more details in the go mod documentation and the Go Modules Wiki.

Pull requests should only modify go.mod or go.sum where it is related to the change at hand, whether a bug fix or a new feature. Apart from that, these files should only be modified by pull requests whose only purpose is to update dependencies.

Copyright

New code files should use one of the standard headers found in the docs/templates folder. Examples exist for Go (also works with CSS), HTML, Jet, and YAML (also works with SQL).

The copyright range should be updated when a file is modified in a year later than the current end of the range.