Project

General

Profile

Day to Day Task #1056

Documentation

Added by Anonymous over 2 years ago. Updated almost 2 years ago.

Status:
Reviewed
Priority:
Normal
Assignee:
-
Motivation:

For the continued development of this project beyond people have to understand fast how to continue develope/contribute to the project.


Description

Write Documentation right away or at least one day a week. (Friday is a good choice. ;) )

Priorities:
  1. Developer documentation
    • This is at docs/ and online at https://ecohackerfarm.github.io/powerplant/.
    • Follow our JSDoc conventions for documenting all files, directories, functions and classes
    • When architecture or the structure of the project is changed, update the overview doc at docs/dev_docs.md.
    • Regenerate online developer documentation at least when docs/dev_docs.md has been changed
  2. User documentation
    1. The components: what are they EXACTLY
      1. Location, garden, bed, crop
    2. How to:
      1. Create a new bed/location/garden
      2. Add a crop to a bed without suggestions
      3. Add a crop to a bed using suggestions
      4. Fill out a bed schedule that has gaps
      5. Check the status of a bed
      6. Add crop or crop relationship information
      7. Submit a bug report/feedback
      8. Probably lots more to be added

Ticket needs to be enhanced


Recurrences


Related issues

Related to powerplant - Day to Day Task #1114: Create and Enhance Small TicketsReviewed

History

#1 Updated by Anonymous over 2 years ago

  • Description updated (diff)

#2 Updated by Anonymous over 2 years ago

  • Description updated (diff)

#3 Updated by Anonymous over 2 years ago

  • Description updated (diff)

#4 Updated by Anonymous over 2 years ago

Developer Documentation for powerplant
Last updated: Jul 15, 2017

Introduction

powerplant is a full-stack JS web app utilizing several external services and many interlocking components. The aim of this doc is to help you, as a developer, get familiar with all the parts of the software. It should act as a roadmap, showing you where each functionality of the software lies, and where each new functionality belongs.

It would be helpful to have
  • A bit of working knowledge of javascript
    • ES6 standards are a plus
  • Understanding of JS Promises
  • Understanding of the principles behind building a React app - see Thinking in React
  • Knowledge of REST principles for building web APIs - see RESTful Web Services

NOTE These would just be helpful. If you're like me, you started with none of these except for a bit of JS.

RELATED If you see something in these docs that you think should be changed or see existing code that you think is leading the project down the wrong path and needs to be refactored or restructured, PLEASE work to change it! The project is in its early stages, and there are many features or implementation details that made it through simply because the project is so small. Also, I apologize if you find any awful code.

You can send questions, complaints, or hate mail to

Setup

To start, you need to set up the development environment. This includes: NodeJS, Docker (with mongo db)

  1. Install Node you should install version 6.x
  2. Install Docker
  3. Install the Mongo Docker image by running docker pull mongo
  4. Clone the git repository
  5. Start the Docker image by running npm run mongo
  6. Run the Firebase data migration by running npm run migrate
  7. At this point, everything should be set up. Run npm test to make sure everything is working, and npm start to begin serving the website on http://localhost:8080
  8. Done!

Architecture

Codebase

The entire codebase, front and back, is written in ES6 using Babel to transpile to CommonJS.

Testing

Tests are stored in the /test folder. The structure of this folder should mirror the root file structure. This makes it easy to find the test module for any module. Tests should be written for every component that contains business logic or helper functions, as well as every API route. No tests need to be written for external library functions (like Mongoose Models). However, if you write an extensions to an external function, like a query function for a Mongoose Model, that should be tested.

Whenever possible, use unit testing to test a single component separate from the rest of the codebase.

If isolation is not possibe, integration tests are ok too. This is necessary for API tests, and possibly also for database functions.

All tests are dispatched with Mocha and use the expect function from the assertion library Chai. API tests use supertest to create requests.

Mocha

https://mochajs.org/, "cheat sheet":

Mocha is the test-running framework which is used to organize the tests. We use the BDD (behaviour-drive-development) syntax, so the main functions used to organize tests are describe and it. describe is used to separate modules and functionalities within modules, and it is used to describe a specific behaviour. Generally, tests for a module are organized with two levels of describe, the first being the name of the module, and the second being for a specific function or functionality. Test code then goes within an it function in the second.

For example:

describe('data-validation', () => { // module name
    describe('#idValidation()', () => { // function name
        it('should validate a correct id', () = > {
            // test code goes here
        });
    });
    describe('#getCompanionshipScores()', () => { // other function name

        it('should return correct scores', () => {

    // test code goes here

    });

    });
});

or

describe('authReducer', () => { // module name
    describe('SET_CURRENT_USER', () => { //not a function, but a specific functionality
        it("should set the current user", () => {
            // test code goes here
        });
    });
});

Mocha tests run synchronously, but it does support asynchronous test code through the use of promises. To test asynchronous code, simply have the it function return a promise. The next test will not execute until the promise is resolved.

Chai

http://chaijs.com/

Chai is the assertion library used for

Supertest

Front end

React, react-router-dom

Redux

React-bootstrap

Webpack

Back end

Node

Express

Mongoose

Common tasks

Front end

Adding tests

Adding a new page

Back end

Adding tests

Unit tests

Integration tests

Modifying the database structure

#5 Updated by Anonymous over 2 years ago

#6 Updated by Anonymous over 2 years ago

Documentation friday was a success yet again!

Using JSDoc and docstrap, I've set up a very nice looking doc site and hosted it on github pages

https://ecohackerfarm.github.io/powerplant/generated/index.html
please ignore the fact that the landing page is in the wrong markdown format

#7 Updated by Franz Gatzke about 2 years ago

  • Assignee deleted (Anonymous)

#8 Updated by Franz Gatzke about 2 years ago

#9 Updated by Franz Gatzke about 2 years ago

  • Tracker changed from Normal Task to Day to Day Task
  • Subject changed from Documentation Fridays! to Documentation
  • Description updated (diff)
  • Start date deleted (07/14/2017)
  • Motivation updated (diff)

#10 Updated by Franz Gatzke almost 2 years ago

  • Description updated (diff)

#11 Updated by Petteri Pitkänen almost 2 years ago

  • Description updated (diff)

Also available in: Atom PDF