Submission Guidelines

So you have decided to submit a project to Elixirland? Great! Here are some guidelines and background information to help you get started.

What is an Elixirland project?

An Elixirland project is a programming task that is designed to help users learn some area of the Elixir ecosystem by building small applications. Projects are meant to be implemented with production-quality code in mind. This means that the implementations should be well-structured, tested, and documented.

Each project also comes with an example implementation that demonstrates how the task can be solved. The example implementations serve as a reference for users who are stuck or want to compare their own implementations with a working implementation. Also, the example implementations serve as a way to showcase idiomatic Elixir code.

Project description

Your project lives in a GitHub repository and, once it is approved, it is published on the Elixirland website automatically whenever your push changes to the repository. Your project's repository contains the project description inside a file called README.md. This file is used to display the project description on the Elixirland website.

Project authors are free to design their project how they wish, but they must follow a minimal set of requirements to ensure consistency and quality. Here is an overview of the different sections that your project description must contain.

Required sections

• Task

  The Task section describes what the user is expected to build in one, or a few, sentences. The task description is likely to leave out a lot of details about the requirements of the project. These details are covered in the requirements section. The purpose of the task description is to give the user a high-level overview of what they are expected to build.

  Importantly, the task description should also specify what resources from the Elixir ecosystem the user is expected to use. This could be a specific library, a particular feature of Elixir, or a combination of both. This information is important because it helps users understand what area of the ecosystem they are expected to learn by solving the project.

  Example:
  Create an API for listing a book club's books, along with the last page that was read.
  
  When implementing the project, you must use:
  - Phoenix
  - Ecto
  

• Requirements

  The Requirements section lists any requirements and constraints the implementation must satisfy. Together with the task description, the requirements section should give the user a clear understanding of what they are expected to build and how they should build it.

The Task and Requirements sections are the core of your project and should appear in the given order and consecutively. However, these sections do not have to be placed at the beginning of your project description. You can add other sections before or after these two sections, as long as they are clearly separated from the task description and requirements and the overall structure follows a logical order.

Here is a list of suggested sections that you can include in your project to help users understand and solve the project. These sections are optional, but they can be very helpful for users who need more context or guidance.

Suggested sections

• Learning Objectives

  The learning objectives describe what users can expect to learn by solving the project. This section is optional but can be helpful for users who want to know what they will gain from solving the task.

  If you add this section, please position it at the very beginning of the project description.

• Introduction

  The introduction provides some background information about the task and sets the context for the project. This section is optional but can be useful for users who want to understand the problem domain better.

  The name of this section can be "Introduction" or any other name that you think is appropriate. Another option is to use the format "Introduction: [subtitle]", for example: "Introduction: Help a Book Club Keep Track of Their Reading!".

• Taking It Further

  The Taking It Further section lists features that the user could implement, in addition to the required features, as an extra challenge. This section is optional but can be useful for users who want to extend the project. The features listed in this section should not be implemented in the example implementation that you provide.

In addition to these sections, you can include any other sections that you think are necessary to help users understand and solve the project. However, make sure to keep the project structure consistent and easy to navigate.

You might wish to add information about how users can get started with their implementation of your project or a reference to your example implementation. This information is, however, automatically added to your project when it is published on Elixirland. Have a look at any of the existing projects on Elixirland to see how this information is presented, so you can decide what to include in your project and what to leave out.

Automatically added sections

• How to get started?

  The "How to get started" section guides users through the process of starting their own implementation of a project. This section prewritten by Elixirland and added to your project when it is published from GitHub to the Elixirland website.

• Where is the example?

  This sections contains practical information about where users can find the example implementation that accompanies the project. This is not where the example implementation is provided. This section prewritten by Elixirland and added to your project when it is published from GitHub to the Elixirland website.

Thumbnail and preview video

When you submit your project for approval, it must include a thumbnail image and a preview video. These assets are used to promote your project on the Elixirland website and help users understand what your project is about. Below are the requirements for the thumbnail image and preview video.

1. Thumbnail image

   The thumbnail image is an image that represents your project. It should give users an idea of what your project is about. The thumbnail image should have the aspect ration 3:2 and have a resolution of at least 600x400 pixels. The image must be in .WEBP format.

   Add the preview video to the root directory of your project repository and name it thumbnail.webp. Elixirland can help you create a thumbnail image if you don't have one. Just reach out to the Elixirland team for assistance.

2. Preview video

   The preview video is a short video that showcases the example implementation of your project in action. The video should not be more than 2 minutes long and give users a quick overview of what your project does. The video should be in .WEBM format and have an aspect ratio of 3:2. The maximum file size is 50MB.

   Add the preview video to the root directory of your project repository and name it preview.webm.

Example implementation requirements

The example implementation is an important part of the project as it serves as a reference for users who are stuck or want to compare their own implementations with a working implementation. To ensure it meets this purpose, the example implementation should be well-structured, thoroughly tested, and properly documented. Below are the key requirements for the example implementation.

1. Correctness

   The example implementation must solve the project task correctly, fully satisfying the requirements outlined in the project.

2. Idiomatic Elixir

   The implementation should be written in idiomatic Elixir, adhering to the conventions and best practices established by the Elixir community. Coding styles and preferences vary, of course, so this is mostly up to the project author.

3. Test coverage

   The example implementation should include tests to verify that it functions as expected. These tests should cover the main functionality as well as any potential edge cases. While it’s not necessary to achieve 100% test coverage, the goal is to demonstrate effective testing practices that align with production-quality code. While this is primarily the responsibility of the project author, reviewers can offer valuable feedback on the adequacy of test coverage. Requiring that the example implementation is tested allows learners to learn to test their Elixir code well.

4. Documentation

   The example implementation should be accompanied by clear and concise documentation. This documentation should explain the purpose of the implementation, how it works, and any significant design decisions. As with test coverage, the documentation should meet the standards of production-quality code. Although more documentation isn’t always better, it should be informative and help learners understand how to document their code effectively.

Getting started

To submit a project to Elixirland, you need to follow a few steps. The process is designed to be straightforward and to ensure that your project meets the quality standards of Elixirland. Below is an overview of the steps you need to take to submit a project.

1. Request a repository for your project

   To submit a project, you need to request a repository from the Elixirland team. This repository will be set up with the necessary structure and templates to help you get started. You can change the template to fit your project, but make sure to follow the project structure and example implementation requirements outlined in this document.

2. Implement

   Once you have access to the repository of your project, you can start implementing the project. Make sure to follow the project structure and example implementation requirements outlined in this document.

3. Request publication

   When you are ready to submit your project, you can request publication by reaching out to the Elixirland team. They will review your project and provide feedback if necessary. Once your project is approved, your repository will be made public and the project will be published on the Elixirland website. Any future changes you make to the repository will automatically sync with the website.

To request a repository for your project, please open an issue in the Elixirland GitHub repository using the button below. Please include a brief statement about what area of the Elixir ecosystem your project wil cover.

Open an issue