Skip to main content

Contributing

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.

Code-generation​

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 ./...

Linting​

Your code will be linted using golangci-lint during CI. To install in locally, follow this guide.

To run it locally:

golangci-lint run

Formatting​

Format your code using the standard fmt command:

go fmt ./...

Unit-tests​

Your code should be covered in unit-tests, see the codebase for examples. To run tests:

go test ./...

Integration tests​

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:

cd internal/integration 
docker-compose up -d

Then run the tests, from with the integration directory:

go test ./...

Contributing documentation​

The Atlas documentation website is generated from the project's main GitHub repo.

Follow this short guide to contribute documentation improvements and additions:

Setting Up​

  1. Locally fork and clone the repository.
  2. The documentation site uses Docusaurus. To run it you will need Node.js installed.
  3. Install the dependencies:
    cd doc/website && npm install
  4. Run the website in development mode:
    cd doc/website && npm start
  5. Open you browser at http://localhost:3000.

General Guidelines​

  • 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​

  1. Add a new Markdown file in the doc/md directory, for example doc/md/writing-docs.md.

  2. The file should be formatted as such:

    ---
    id: writing-docs
    title: Writing Docs
    ---
    ...

    Where id should be a unique identifier for the document, and should be the same as the filename without the .md suffix, and title is the title of the document as it will appear in the page itself and any navigation element on the site.

  3. If you want the page to appear in the documentation website's sidebar, add a doc block to website/sidebars.js, for example:

  {
    type: 'doc',
    id: 'writing-docs',
  },
+  {
+    type: 'doc',
+    id: 'contributing',
+  },