Skip to content

Latest commit

 

History

History
304 lines (224 loc) · 11.2 KB

CONTRIBUTING.md

File metadata and controls

304 lines (224 loc) · 11.2 KB

Contributing

Table of Contents

Overview

Any issues or pull requests must adhere to the guidelines below. Any that do not will be closed. You will find more detail about each guideline throughout the rest of this document.

Issues

Before making a pull request, please create one of the following issues:

Pull Requests

Please make sure that your pull request follows these guidelines:

  • There is a corresponding issue.
  • For a sample program article, there is a corresponding stub. This stub is auto-generated by the website automation and is in https://sampleprograms.io/projects/<project-name>/<language>/. For example, https://sampleprograms.io/projects/baklava/ada/. You can tell that this is a stub because the "How to Implement the Solution" and "How to Run the Solution" sections indicates that the section is not available. For more information on how to write a sample program article, see this and this.
  • For a language article, there is a corresponding stub. This stub is auto-generated by the website automation and is in https://sampleprograms.io/languages/<language>/. For example, https://sampleprograms.io/languages/ada/. You can tell that this is a stub because the "Description" section indicates that the section is not available. For more information on how to write a language article, see this and this.
  • The Website Automation passes.

Articles

General Guidelines

Please make sure that your article follows these guidelines:

  • All articles go in folders under sources folder, not the docs folder. The docs folder is used to generate the website.

  • All articles are written using Markdown. If you are unfamiliar with this, please refer to this guide.

  • If you use someone else's work, please cite your references.

  • If your article requires multiple files (such as a sample program article) and you use numbered references, the numbers must be unique. For example, you have this for your last numbered reference in the first file:

    [11]: https://www.gnu.org/software/make/manual/html_node/Make-Control-Functions.html#index-info

    and you have this for your first numbered reference in the last file:

    [12]: https://leangaurav.medium.com/how-to-setup-install-gnu-make-on-windows-324480f1da69

  • If your article has multiple sections, they must start at level 3. For example:

    ### Setup

...

### Input Validation

...

Sample Program Article

A sample program article describes an existing sample program in the Sample Programs repository.

Files for this article are placed in the sources/programs/<project>/<language> folder, where:

  • <project> is the project name in lowercase, with spaces converted to dashes. For example, binary-search for the "Binary Search" project.
  • <language> is the language name in lowercase, with spaces converted to dashes, and symbols like + converted to words. Examples:
    • c-plus-plus for C++
    • c-sharp for C#
    • google-apps-script for Google Apps Script

This folder must be created. The next sections describe the files that go into this folder. Images go into the same folder. These are optional. See Images for details.

how-to-implement-the-solution.md (manditory)

This file contains a description of how the sample program works. There is no need to copy/paste in the entire program into this file; that is automatically done by the website automation. Instead, you may show portions of the code with explanations around them. The code is enclosed in triple-backticks followed by the language name (use the same name as <language> shown above). For example, here is a description of a portion of code written in Go:

Breaking down this solution bottom up,
```go
func main() {
    if len(os.Args) != 2 {
        exitWithError()
    }

    nums := strToSliceInt(os.Args[1])
    nums = bubbleSort(nums)
    fmt.Println(sliceIntToString(nums))

}
```
This is the `main` function of this file. It parses ...

how-to-run-the-solution.md (manditory)

This file contains instructions on how to run the sample program. It should contain the following:

  • Instructions on how to download and install the programming language.
  • What commands are needed to build (if applicable) and execute the code.

Alternatively, you can document how to use an online tool that can be used to run the code. For example, programviz.com has an online C++ compiler into which you can copy/paste the sample program and run it.

Language Article

A language article describes an existing language in the Sample Programs repository.

Files for this article are placed in the sources/languages/<language> folder, where:

  • <language> is the language name in lowercase, with spaces converted to dashes, and symbols like + converted to words. Examples:
    • c-plus-plus for C++
    • c-sharp for C#
    • google-apps-script for Google Apps Script

This folder must be created. The next sections describe the files that go into this folder. Images go into the same folder. These are optional. See Images for details.

description.md (manditory)

This file contains a description of a programming language. It should contain enough detail to give an overview of the language. It may contain snippets of code with explanations around them. The code is enclosed in triple-backticks followed by the language name (use the same name as <language> shown above). For example, here is a description of a portion of code written in D:

Perhaps the most interesting feature to me has to be the inline 
assembler. Apparently, developers can write assembly code directly 
in D source code:

```d
void *pc;
asm
{
    pop  EBX;
    mov  pc[EBP], EBX;
}
```

Images

Images may be one of the following (unless otherwise noted):

  • Images stored in the same folder as the article. Let's call these local images.
  • External images that are referenced by their URL.

General Guidelines

Please make sure that your images follow these guidelines:

  • Do not use copyrighted images, images that require royalty payments, or any non-free images.
  • Do not use images that have watermarks on them. That is usually an indication that the image has usage conditions that are incompatible with this site.
  • Do not use images or sites (for external images) that violate the Code of Conduct.
  • For external images, these must come from free sites that do not require a login.
  • If an image requires an attribution, this must be added somewhere in the article, preferrably close to the image in question.
  • Images must be in one of the following formats:
    • JPEG (.jpg)
    • PNG (.png)
    • GIF (.gif)

Here are some good sources for free, non-copyrighted local images:

Title Image

This image is placed at the top of articles. This must be a local image, and the file name must be one of the following:

  • featured-image.jpg
  • featured-image.png
  • featured-image.gif

Please do not use any animated GIFs for this. The recommended size is 1200x628. The image is modified by image-titler which handles resizing, cropping, and decorating the image with the logo, and that size works best. The website code itself handles adding the image title.

If this image is not used, then a default image is used. For sample program articles, this is the same image as the project:

  • Navigator to here.
  • Click on the project.

For language articles, this is the default image.

Other Images

Other images may be added to your articles to help clarify key points more clearly than words alone.

Local Images

Local images are referenced like this:

![Name of image](<image-directory>/<image-filename>)

where <image-directory> is one of the following directories, and <image-filename> is the filename of the image:

  • Sample program article: /assets/images/projects/<language>/<project>
  • Language article: /assets/images/languages/<language>

For example:

![Annotated Baklava in Piet](/assets/images/projects/baklava/piet/baklava-annotated.png)

External Images

External images are referenced like this:

![Name of image](<url>)

where <url> is the website to the image. For example:

![Example Graph](https://media.geeksforgeeks.org/wp-content/uploads/20210727035309/UntitledDiagram92.png)

Building Website Locally

Prerequisites:

If you wish to build a local copy of the website, create a virtualenv, activate it, and install requirements.txt:

virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt

You should only need to do the above once. All other times, just activate the virtualenv with the source command.

Now, run ./generate.sh. This will build the website, create a temporary web server, and open up the home webpage in your default browser at http://localhost:8000/index.html. When you are done, just press Ctrl+C to exit the web server.