75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# 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](https://git.erbosoft.com/amy/amsterdam). 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](https://links.inclusiveladyship.com/@amy) for access.
|
|
|
|
## AI Contribution Policy
|
|
|
|
As per our [Code of Conduct](CODE-OF-CONDUCT.md), 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](https://github.com/tailwindlabs/tailwindcss/releases/) 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](https://git.erbosoft.com/amy/amsterdam/issues/new) describing the problem or proposed feature.
|
|
2. Discuss the design with [maintainers](MAINTAINERS).
|
|
3. Submit a pull request referencing the issue.
|
|
4. Participate in code review.
|
|
|
|
## Versioning
|
|
|
|
Amsterdam employs [semantic versioning](https://semver.org/), with version numbers in the "major.minor.bugfix" format. Please see
|
|
the linked specification for further details.
|
|
|
|
## Git Branching
|
|
|
|
Amsterdam employs the [GitHub Flow](https://docs.github.com/en/get-started/using-github/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](https://go.dev/cmd/go/#hdr-Module_maintenance).
|
|
You can find more details in the [go mod documentation](https://go.dev/ref/mod) and the [Go Modules Wiki](https://github.com/golang/go/wiki/Modules).
|
|
|
|
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.
|