How to Contribute
Atlas is a community project, we welcome contributions of all kinds and sizes!
Here are some ways in which you can help:
- File well-written and descriptive bug reports or feature requests in the Issues page.
- Tweet about your experience with Atlas on Twitter, don't forget to mention @ariga_io and link to atlasgo.io if you do.
- Write educational content on your personal blog or websites such as dev.to or Medium. If you do, don't hesitate to reach out to us via Discord (link below) for help proof-reading your text and using our social-media channels for distributing it to readers.
- Join our Discord Server to answer questions of other users and find out other ways in which you can contribute by talking to the community there!
- Contribute bug-fixes or new features to the codebase.
Contributing code to Atlas
As we are still starting out, we don't have an official code-style or guidelines on composing your code. As general advice, read through the area of the code that you are modifying and try to keep your code similar to what others have written in the same place.
Some of the code in the Atlas repository is generated. The CI process verifies that
all generated files are checked-in by running
go generate ./... and then running
git status --porcelain. Therefore, before committing changes to Atlas, please run:
go generate ./...
Your code will be linted using
golangci-lint during CI. To install in locally,
follow this guide.
To run it locally:
Format your code using the standard
go fmt ./...
Your code should be covered in unit-tests, see the codebase for examples. To run tests:
go test ./...
Some features, especially those that interact directly with a database must be verified
in an integration test. There is extensive infrastructure for integration tests under
internal/integration/ that runs tests under a matrix of database dialect (Postres, MySQL, etc.)
and versions. To run the integration tests, first use the
docker-compose.yml file to spin up
databases to test against:
docker-compose up -d
Then run the tests, from with the
go test ./...
The Atlas documentation website is generated from the project's main GitHub repo.
Follow this short guide to contribute documentation improvements and additions:
- Locally fork and clone the repository.
- The documentation site uses Docusaurus. To run it you will need Node.js installed.
- Install the dependencies:
cd doc/website && npm install
- Run the website in development mode:
cd doc/website && npm start
- Open you browser at http://localhost:3000.
- Documentation files are located in
doc/md, they are Markdown-formatted with "front-matter" style annotations at the top. Read more about Docusaurus's document format.
- Atlas uses Golang CommitMessage formats to keep the repository's history nice and readable. As such, please use a commit message such as:
doc/md: adding a guide on contribution of docs to atlas
Adding New Documents
Add a new Markdown file in the
doc/mddirectory, for example
The file should be formatted as such:
title: Writing Docs
idshould be a unique identifier for the document, and should be the same as the filename without the
titleis the title of the document as it will appear in the page itself and any navigation element on the site.
If you want the page to appear in the documentation website's sidebar, add a
website/sidebars.js, for example:
+ type: 'doc',
+ id: 'contributing',