Project Maintenance

Project, User Project or Blog Post?

If you want to publish your open source software, there are generally three approaches to start:

  1. Create and Maintain an Open-Source Project, shared with others
  2. Create a User Project, which is published in your profile
  3. Just publish your code and some pictures in your private Blog

The decission should be easy:

  • If you have serious plans with your project, choose option (1)
  • If you just want to share your idea and use the SVN or Git infrastructure of Forge, choose option (2)
  • If you just have a project, which you don't want to maintain, but share it once, choose option (3)

Despite of your choice, you can use the Wiki or Blog post to:

  • Describe your project in "markdown" syntax
  • Embed Youtube Videos
  • Embed Screenshots or Schematics
  • Upload Files

Create a project

To create a project you need to:

  • be logged in with your account
  • know your neighborhood

The login should be very streight forward, but what is a neighborood?

Neighborhoods can be seen like fix categories in which you create your project.

Technically they are special purpose projects which can also host documentation.

Neighborhoods

CODESYS Forge categorizes its projects into the following neighborhoods. Please take a look into the documentation of your choosen neighbourhood, to understand the rules which aply to it.

Projects

These are projects, realized with CODESYS. Some examples can be:

  • a heating control system
  • a control application for drones
  • a weatherstation
  • ...

... or even industrial applications where the knowhow is lying more in the materials, physical parts or mechanics, and where the software is only a small part. Why shouldn't companies share such knowledge, which is far away from their main business?

Libraries

CODESYS libraries are a special kind of a project, which can hold POUs, Visualizations, etc., which you want to share across various different applications and projects.

Drivers

This neighbourhood consists of all kind of software, which enables CODESYS to access any kind of hardware or remote software stacks.

Tools

This neighbourhood should contain all kinds of tools on the host or the target, which are interacting with CODESYS or extending the functionality of CODESYS or one of its applications.

Hacks

This is a public project, where everyone is welcome to post his little helper scripts and snippets. For this reason, the central element to maintain the code is not Git or SVN, but simply a blog.

Targets

CODESYS supports various open PLC platforms. This neighbourhood contains projects for all of those which are directly or indirectly supported. It's a place to collect hints, scripts, and documentation to operate those targets.
It's mainly a place to share valuable information about those targets.

Project Tools

Every project can be configured differently. As the mainainer of such a project it is up to you to decide which tools of CODESYS Forge you want to use. Each tool can be added multiple times to a project, with different names. This allows you for example to have one Wiki for your documentation, one as a replacement of a full website and one containg your releases.

By default multiple tools of the same type are grouped together. To avoid that, you have to:

  • Click on the lock symbol on the right of the projects menu bar
  • If you have already grouped menu entries, a setting named "group threshold" will appear. Just increase this value.

Rights

We recommend to keep your project open by default. This way you make it easy for others to contribute.
To make it open, switch to the "Permissions" tab in tools and add "*authenticated" to the "Create" and "Edit" rights. This will allow every CODESYS Forge user to contribute to this project and this tool.

By default, you will be notified via E-Mail when s.o. contributes to your project.

Documentation

Documentation might be the most important part of your project. It gives you the chance to explain your users what they can expect from your project and how it can be used.

The documentation is written in form of a Wiki, like it is best known from Wikipedia. You can insert as many of those wikis with different names as you want.

Before you start with your documentation you should have a look into projects of your neighbourhood. You might find plenty of good ideas there.

The following are hints for some good practices to document your project.

ToC / Index

Your wiki will most likely grow and consist of different pages. It is generally a good idea to put some thoughts into the structure of your pages in advance.

A good practice is to do this in form of an own wiki page, which consists solely of links to the pages you planed. Maybe with an additional "table of content" of the current page.

* Installation
    * [Install the package](InstallPackage)
    * [Compile from source](InstallSource)
...

This page can for example be named IndexMain and be included in every other page which you start afterwards.

You can include a page like this:

[TOC]

[[include ref=IndexMain]]

Contribution Notes

Contributing to a project is not easy. You need to make yourself familar with the people behind the project, as well as the

  • project structure
  • coding rules
  • restrictions
  • commit rights
  • branch and merge process
  • ....

To make it easier for your users to understand your rules, and for you to explain them, we collected a few process desciptions which might apply to you. You can link them on your own Contribution wiki page with the following link:

[General rules for contribution](forge:documentation:Contribution)

Please check the Terms of Service for more informations about the legal aspects of sharing code.

You can freely choose a license under which your project is published. While encourage you to choose the MIT or Apache license, as those are giving your users the most rights.

If some special constraints apply to your project, which are not covered by the general ToS, please add a documentation page for your users to clarify this.

SVN / Git

Please check the documentation regarding Souce Code Management. There you'll find a detailed description of your options.

You can add as many code repositories to your project as you like and also name them as you like.

Bug Tracking

CODESYS Forge is featuring a minimalistic bug tracking system. Please check the documentation for a description of the ticket system.

Blog Post

To publish s.th. in your Blog, just use the link in your Dashboard.

Embedding Videos

To embed a video, you have to upload it to youtube first. The youtube link can then be embedded into your blog post.

E.g.:

...
I managed to get an amazon echo connected to my BBQ smoker. Check this out to see it in action:

[[embed url=http://www.youtube.com/watch?v=XYZ]]

Embedding Images

Images can be directly attached to your post after you posted it. Sounds a bit strange, but you can only attach s.th. to the post after it exists.
So if you want to embed an image into your blog post, you have to follow the following steps:

  1. Create your textual post
  2. Edit your post
  3. Attach your images
  4. Embed the image like this...
Small Image:
[[img src=Layout_schem.png/thumb]]

Full sized Image:
[[img src=Layout_schem.png]]

Just use the file name of the image, or attach '/thumb' to get a smaller version of the image. The files can always be viewed by your users in full size by klicking on the attachment.

Design and Content

For us developers, it is often not easy to present our briliant ideas in a nice looking way. To make it a bit easier for you, we collected a few tips and tricks for an easy but nice looking presentation.

Hardware Layout / Design

Drawing a hardware layout is already a difficult task. If you add some more attributes to the task, it becomes a tough job:

  • The layout should be accurate, so that it is easy to build for others.
  • You should have some nice and colorful sketches for beginners.
  • The images should not contain any images which have to be licensed.

There is an open source tool, which enables everyone to create such neat sketches and layouts:
Fritzing

  • As it is conceptionally easier, you can start with a schematic:

  • And for free, you get this nice looking sketch:

Parts for your Layout

Fritzing already contains lots of parts in its default installation. But here are a few ressources, where you can find larger libraries of parts:

As most of us are no designers, we provide you some Logo Icons, which can be used freely. They are based on the famous "font-awesome" set of icons. But they are preprocessed, so that they can be directly used as a project logo.

You can find the icon set in this SVN repository

Some examples...

Building Code-Branch Code User-Secret
Building Code-Branch Code User-Secret

Related

Wiki: Home
Wiki: IndexMain