Problem

The current starting page of the documentation contains 2 pictures that aren't shrinked and it is not clear why.

Solution

To Be Developed

Notes

None yet

Problem

In a mailing list a guy named Tarek Ziadé mentioned that configuration could either be done in or another data structure grammar (XML, YAML, ...) or could be done directly with ConfigParser, which seems to be a good enough decision, especially since ConfigParser is part of the standard library.

Is it enough? What are our requirements?

Solution

Find out what ConfigParser can do.

Notes

At the moment this is basically a stub, that I don't forget about this possibility.

Problem

There is a file in MONK's source folder called uuid_.py which seems to be a nearly exact copy of a file that seems to be part of the Python standard library (on my Xubuntu 12.04 it can be found at /usr/lib/python2.7/uuid.py). Checking with grep it is used nowhere in the rest of MONK.

Solution

Delete the file and see if anything breaks. At the moment it seems reasonable, because it seems quite useless.

Notes

changes will be added to branch f-remove-uuid

Problem

The current contributing.rst is merely a list of dos and don'ts. Neither does anybody want to read that nor does it really tell people how to develop for MONK. I feel that this page should mostly be a guide going step by step through installing the system requirements, creating the development environment, running the test suite and making a little change to MONK. Only in the end should be the rules and details for people who want to dive in more deeply or iif the team needs some arguments for decision making. But those cases are rare.

Solution

Create tutorial with git, virtualenv, test suite and use this issue as example for making a change to MONK.

Notes

• For reviewers:

  • the spell checking will be done after @toang is back from her holidays

  • to close this task you need to build the docs without warnings and errors with

    # somewhere in your filesystem
    somewhere$ git clone -b f-docs-devenv [email protected]:DFE/MONK
    somewhere$ cd MONK
    MONK$ virtualenv .
    MONK$ . bin/activate
    (MONK)MONK$ pip install sphinx
    ...
    (MONK)MONK$ python setup.py develop
    ...
    (MONK)MONK$ cd doc
    (MONK)doc$ make html
    (MONK)doc$ chromium-browser build/html/contributing.html
    # read if you can understand it in most cases -> ACK
    (MONK)doc$ deactivate
    doc$
    

• changes will be added with f-docs-devenv

Problem

If no cmd is sent to the serial connection for a long time and simultaneously a lot of outputs are written to the console this may result in a freeze of the serial connection.

This typically occurs, if you send the first command to the device only after a few minutes. In this time a lot of kernel output is written from a hipox device.

To reproduce the problem you can use the following short program.

#!/usr/bin/env python

import unittest
import time

from MONK import devicetestcase

class TestSERIALPROBLEM(devicetestcase.DeviceTestCase):

    def __init__(self, *args, **kwargs):
        super(TestSERIALPROBLEM, self).__init__("hipox", *args, **kwargs)

    def test_serial_problem(self):
        self.dev.conn._serial.cmd("date")
        time.sleep(10)
        self.dev.conn._serial.cmd("date")
        time.sleep(300)
        self.dev.conn._serial.cmd("date")

def main():
    unittest.main()    

if __name__ == '__main__':
    main()

Start the program, login to the device using SSH (when this is available) and generate heavy output to /dev/console, for instance with

while true; do
    date > /dev/console
    sleep 1
done

Solution

No solution found yet

Notes

• branch f-serial-thread

Problem

The current documentation doesn't tell a user well enough how to integrate MONK in it's test cases and how to work on MONK separately while running their own test suite.

Solution

A tutorial comparable to #36, but for the user.

Notes

• Experiences already made by @DMSPeterWinkler and @infeix
• Changes in Branch f-userenv-tutorial

Problem

In monk we use the pyserial framework for serial connections. Yet serial itself is not a standard like USB.

Solution

Investigate what a serial connection is, how the standard works, which options exist and which errors might be possible.

Problem

The doc/README was written in markdown, but is not recognized as one, because it has no file ending .md or the likes.

Solution

Move the README to README.md and create a unix link to the latter.

Notes

Changes are tracked in f-doc-readme-md

I suggest to develop a configuration(-file) to be used by the software engineer during testcase code development. The configuration should make it easier for the programmer to activate or deactivate special parameters in the code. For example : reseting of a device at the beginning or the end of a testcase.
This would save valuable time, cause the programmer hasn't got to wait for 2 minutes until the device is rebooted each time he wants to debug his test.

Options

1. Using an external configuration file

Using an external configuration file, which is read and evaluated by the devicetestcase and their methods. If a flag is set in the configuration file, it won't be used by the devicetestcase-class and instead the class uses "normal" parameters

• Advantages:
  • only one source has to be changed one time, one additional configuration file
  • central source
• Disadvantages:
  • errors in configuration file could create strange behaviour during code execution

2. Manually manipulating the code

Manually manipulating the code, if it is needed ( on the fly)

• Advantages:
  • fast method
• Disadvantages:
  • you have to know, where the function is placed in the code
  • you have to understand the code completly
  • maybe you will forget, what you have done... searching an error would cost valuable time
  • "pushing code" is more risky

3. Divide and Conquer (added by @erikb85)

Abstracting complicated code outside the TestCases.

• a TestCase itself should be so easy to understand, that in most cases there shouldn't be any need for debugging
• The complicated code can be written seperately and also tested seperately
• This is exactly what the Gordon-FW is written for!
• Advantages:
  • following community best practices
  • applying a general design pattern divide and conquer
  • using the framework as it was meant to be
  • having tested execution steps and simple TestCases
• Disadvantages:
  • Testdesign and -development time increases
  • doing it incorrectly or overdoing it will hide important details about a TestCase which makes it actually more bug prone and less readable.

4. Use environment variables (inspired by @infeix, see comment below)

Use specific environment variables

• Advantages:
  • fast and easy method
  • configuration is not centralized
• Disadvantages:
  • configuration is not centralized

My opinion

I would use Option 1.Feel free to comment and make own suggestions.

Situation

For running the test suite and building the docs there should be a Jenkins Job file, which can be simply integrated.

Solution

Configure and test a Jenkins job, then export the configuration to a file in this repository.

Notes

• feature branch f-jenkins-config

Problem

Logging with a logging.conf file either makes the code more error prone or requires the user to always have the file in the local path, where he starts to use MONK. Thus another logging solution must be found.

Solution

One suggested and already implemented solution is to configure the logger in the code. As long as the configuration doesn't get too complicated it is actually easier to maintain, because everything is written in Python directly.

Notes

This issue mainly serves the purpose to add documentation to a change made some weeks ago.

This commit was denied at first for the following reasons:

• The information delivered by the commit was too dense. It was never really clear to anybody, what problem was actually solved.
• The changes weren't protected by unit tests.

After discussing with @sledz and @marioecht, we decided that it would be better to check in the changes separately and comment the changes more clearly. That's what this issue is about.

Further notes:

• Commits for this issue are checked into the branch f-logging-rework-v2

Situation

Travis-CI is a public, free-to-use, open source CI server, which intergrates automatically quite well with github.
The only CI we are using right now is our local Jenkins.

Improvement

It would make sense to make use of the free CI server in the cloud, if one is available. At least a minimal integration should be approached.

Notes

Changes are tracked in branch f-add-travis-support

This is a forward from the mailing list:

Problem

Currently MONKs SSH connection class opens a new SSH connection every time a
command is called, just to close it again after usage. Although the opened session is stored internally in self.__session the code itself, doesn't validate, whether a formally created session is still valid to be reused again (see the code).

Solution

For perfomance optimization it would be nice to add such a reuse of created SSH sessions.

Comments

Until now I won't take responsibility for solving this issue and just posted it here for documenting reasons.

Situation

As described in a comment to the research Issue #53 the following possible error sources in serial connections where found.

Typical Problems

• sync time in the beginning (probably needs active I/O)
• one side might lose characters on the way
• one side might misinterprete characters
• one side might have different baudrates
• one side might have differently working clocks (which leads to misinterpretation of baudrates)
• one side might stop sending because it waits for a control signal (hardware or software flowcontrol activated on one side only, or control characters lost)
• one side might drop received data because it waits for a control signal (hardware or software flowcontrol activated on one side only, or control characters lost)
• if the connection is lost for some time mid-sending it's quite hard to find the beginning of the next character (might be solvable by small periods of at-least-one-frame-long waits)
• cable length might lead to timing errors
• cmd() output might have breaks, that are much longer than reasonable timeouts
• the cmd() call might spend more time idling or polling the connection than necessary, because he already has all output he needs
• kernel output might turn an otherwise useful cmd() call into garbage, which might be handled with a kmod system call on the target device

Solution

The SerialConn must respond to each of those problem sources, probably at least in one of the following ways:

• recognize when such an error happens
• inform the user about this problem (Logging and/or Exceptions)
• react with a default handling
• enable configuration and modification of the error handling

Notes

• this Issue requires #60 to be closed first.
• branch f-serial-errors
• because there are a lot of different points, it is likely that this Issue will be solved in steps with other Issues

Problem

current Sphinx builds contain 10 warnings, which shouldn't be there and the source files are not always referenced correctly (which is told by some of the warnings as well).

Solution

From already finished experiments I can say that:

• The warnings are probably coming from Sphinx issues with the restructured and renamed project. So a solution that seems to work is recreating the project and adding the .rst files to that instead of reconfiguring the current Sphinx project.

Notes

• commits will be added to f-recreate-docs

Situation

The current implementation of SerialConn already offers a simple interface:

>>> import monk_tf.serial_conn as msc
>>> serialconn_obj = msc.SerialConn([details])
>>> serialconn_obj.cmd("ls")
bin coding Desktop Documents Downloads [...]
>>>

It is very likely that the functionality can be improved, now that we have more experience with the interface and the pyserial framework.

Task

Look into the serial_conn module and review the implementation of the cmd() interface and fundamental functionality. An implementation that only considers the best case is fine, because error handling will be added in another step.

Notes

• branch f-review-serial-cmd
• brain storming proposal
• first review
• second review
• current proposal

Problem

The documentation still talks about Hidav's integration layer.

Solution

Rewrite the layer to tell readers about what MONK should help them with and a small example/tutorial, as well as a TOC.

Notes

• changes are tracked in f-docs-overhaul

Problem

Sphinx is not configured for virtualenvs. Every sphinx-* tool starts with the following line:

#!/usr/bin/python

That's why it is not possible to use sphinx correctly in a virtualenv to build the documentation.

Solution

Don't install Sphinx globally into your system. Instead enable installing Sphinx inside a virtualenv.
For more details look into the commit message.

Notes

• changes in f-sphinx-virtualenv

Problem

Maintainer Process is not yet explained in the documentation, only in the wiki.

Solution

• add maintainer processs to the documentation

Notes

Problem

MONK's unittests currently run the sourcecode on system.path modifications, which is kind of hacky. Now that MONK can be installed in different ways, the unittests should also run such an install and simply import monk_tf withouth anything else.

Solution

• deleting the system.path line
• correcting the import to import monk_tf as monk
• changing the test code accordingly

Notes

• see branch f-unittests-virtualenv

from the wiki pages:

• https://github.com/DFE/MONK/wiki/Commit-Policy
• https://github.com/DFE/MONK/wiki/Patch-Mailing-Policy

Problem

MONK has no real open source license yet.

Solution

Find out, what the keywords in licensing are, which are the most important open source licenses and on which basis they can be compared. Detail the information about the resources used for the research as well as the differences between those licenses, so that based on this issue a decision can be made, which license is to be applied to MONK.

Notes

This issue contains only the texts linked here and a presentation in the Google Driver folders of DResearch Fahrzeugelektronik GmbH. A review of the presentation should be sufficient to close this Issue.

1. Overview Investigation
2. Licenses / Details
3. Decision Making Helpers
4. Presentation - Exists in DFE-GoogleDrive, public link possible?

Problem

There is no documentation about configuring the test environment yet.

Solution

I would like to add a paragraph "Configuration Test Environment" in the index of the documentation. That would help to start working with a new environment.

Notes

• changes are added to the branch docs-update-testenvironment-v4

Problem

The setup.py should know on which projects MONK relies, that pip can install everything necessary automatically.

Solution

Add the requirements parameter to the setup() call in the setup.py with the required modules from requirements.txt:

• pylibssh2 (in v1.0.1 if possible)
• pyserial (in v2.5 if possible)

Notes

• changes will be tracked in f-setup-with-requirements

Observation: If a unittest.testcase using the serial_conn class finish in error state, then the serial connection will freeze and block the communication between the host and device. It seems as if one side cancels the connection, while the other one does not. It is unclear which one, though.

There need to be done some real research effort here in finding what exactly causes the problem, what exactly is the problem and how to remove it.

I also found a workaround with switching hardware- and software-flowcountrol, which seems to remove the error state and lets you continue to work normally. Thus this error shouldn't be considered all too critical.

The new tutorial in #36 is not reviewed for spell checking yet. I hope you could do that, @toang. :-)

Problem

The diagrams look somewhat prototypical.

Solution

Find someone with the skills to improve the diagrams.

Notes

Changes are added to the branch f-mengqiaos-diagrams

Problem

There is no discussion of the user process yet available.

Solution

Describe:

• how to install MONK (right now possible)
• how to configure MONK (future plan)
• how to modify MONK locally (right now possible)
• how to hack MONK and why it is not recommended and supported (right now possible)

Notes

Problem

In the function main() of the File monk_tf/ssh_conn.py the class itself is called with a wrong number of arguments. One of the arguments is a logger. This logger is not expected anymore and is removed.

Solution

• commit: aa159ed

Notes

• changes added with f-change-ssh-call

Problem

If the command to be executed, does not return within an unknown timeout the ssh connection failes with:

/usr/lib/python2.7/threading.py:827: RuntimeWarning: tp_compare didn't
return -1 or -2 for exception
return _active[_get_ident()]

Solution

None yet.

Notes

None yet.

Problem

The explanation about how to develop for MONK is in the Wiki, but not in the documentation yet.

Solution

• add developer process to the documentation (extra page code-of-conduct)
• explain patch rewriting workflow
• reference the hacking MONK description in the user process documentation

Notes

Problem

• The automated testsuite contains empty files
• The existing testcases aren't executable by themselves
• Some imports, namings and comments are incorrect, at least from the point of view of renaming project
• important this needs to be done to generally make the tests executable. Making the testsuite succeed can only come afterwards. So executing it and getting a fail is a good result for this task.

The reason for this state was an experiment with a test-coverage framework. But the results are rather inconvinient, i.e. imports that require yor git repository to be written in a specific way as well as the problems described above.

Solution

• change the global testuite and place it in the right spot with the often used name test_all.py, which will likely become coding standard for MONK anyway
• make testcases executable by themselves and in the context of the global testsuite
• add a hull to empty testcases, that they also fulfill the requirements for self-executability and add them to the testsuite, so that someone filling these testcases can't forget to add them to the suite afterwards.

Notes

• The branch for this issue is f-improve-testcases-v2c

Problem

While working with Travis-CI I found that calling our Python scripts as Python scripts doesn't work everywhere as expected.

A lot of Python projects, like public build servers or a web services, don't run their system's Python binaries, but create a small virtual environment around their code, with their own binaries and python modules. One reason for this is that you can easily create the same environment on another machine. Another reason is security. It is a lot like a small virtual machine for Python projects.

Because it is used so often, our scripts should be able to also run in such an environment. Maybe one day we want to decide to also run our tests in a virtual environment or don't want to use the Python binary under /usr/bin.

Solution

Instead of writing in the first line

#!/usr/bin/python

We could also write

#!/usr/bin/env python

env is a tool that automatically looks into the PATH before choosing which Python binary to use.

Notes

Changes are checked into f-better-binary-call-v2

Problem

The issue with the current folder naming is, that it is not compliant with general ideas about the future development in the Python community. The changes are also minimal.

Solution

1. $ git mv tests test
2. edit the test command in the .travis.yml file.

Notes

• changes won't be testable, because the distutils don't support this feature yet, as far as we know.
• changes will be added to branch f-rename-test-dir

Problem

In the Stammtisch we decided, that the Readme (dev version) should tell MONK users, that MONK will be build in Travis-CI and that the current system state can be reviewed there.

Solution

Add a line to the README with a short explanation and a link to the Travis Job

Notes

Changes will be tracked in branch f-add-travis-to-readme.

Problem

The current Jenkins configuration includes a post-build-step to delete the workspace. The idea of that decision was, that the workspace itself is not needed and test results are more meaningful, if the job is built from a fresh workspace. However, removing the workspace after the build results in Jenkins thinking, that it finds an unbuilt state in the GitHub repo and therefore starts a new build, every 5 minutes.

Solution

Delete the workspace before the build instead of after it.

Notes

• branch b-jenkins-delete-ws-before
• that configuration now is already used in our Jenkins
• reviewers make sure, that Jenkins now doesn't build every 5 minutes. Build 941 is the one that I tested the new config with.

Problem

There are a lot of Open Source lincenses out there and MONK has none.

Solution

• Finding and comparing the most important existing licenses and their requirements
• Presenting and discussing them at a Stammtisch

Notes

• Will be discussed in a doc/... page
• changes added to f-compare-licenses

Problem

The parameter timeout of the function read_until is not correctly in use. That is the reason for not terminating tests, waiting without an end.

def read_until (self, target, trigger_write="\n", timeout=None):
"""
[...]
:param timeout: custom timeout for :py:obj:`trigger_write`
[...]
"""

I found the Problem cause of this Log printings:

2013-03-21 17:11:02,824 DEBUG serial_conn.py::read_until(): Triggering with [%0A] target [%0A]

Solution

There is a loop in the function witch is not terminating:

while not target in buf:
        ret = self.read()
        if ret == "":
            self._logger.debug("Triggering with [%s] target [%s]" 
                                    % (urllib.quote(trigger_write), urllib.quote(target)))
            time.sleep(0.25)
            self.write( trigger_write )
        else:
            buf += ret
            if ret == '\n':
                self._logger.debug("[%s]"  % log_line.strip())
                log_line = ""
            else:
                log_line += ret

An Idea of mine is to create a timer for the loop and to decrease it about 0.25 after sleeping 0.25 seconds.

Problem

To install monk_tf with pip you need to install some system packages that can't be mapped in the setup.py, because they are not relevant to Python. You will eventually see an error message like that:

Downloading http://pypi.python.org/packages/source/p/pylibssh2/pylibssh2-1.0.1.tar.gz#md5=b50b6b276703c9283797a294236b83e7
Processing pylibssh2-1.0.1.tar.gz
Running pylibssh2-1.0.1/setup.py -q bdist_egg --dist-dir /tmp/easy_install-xJQdCq/pylibssh2-1.0.1/egg-dist-tmp-yyhmejsrc/pylibssh2.c:21:20: fatal error: Python.h: No such file or directory
compilation terminated.
error: Setup script exited with error: command 'gcc' failed with exit status 1

The reason for this is that the required pylibssh2 package will need to build itself before it can be used. And for building it you will need:

• python-dev
• libssh2-1-dev

Solution

Python itself has no solution for handing non-python requirements, yet. Creating one ourselves might also be rather complicated and work intensive. At least at the moment this amount of work is not justified.

So the only reasonable solution seems to be to add that information to the README and the documentation.

Notes

Changes are added to the branch f-troubleshooting-install-requirements.

Problem

There are some Readmes and Inline Comments, which need to be fixed to correctly finish the renaming.

Solution

Rewriting the READMEs and Inline comments.

Notes

• this Issue is not about changing the Sphinx documentation for the Framework.
• changes were tracked in a branch named f-change-readmes

Problem

RTD has a problem with system requirements. They won't allow installing those, only Python dependencies. One of our dependencies, libssh2, requires system dependencies, though.

Solution

RTD offers a solution which is a little hacky, but should work in general.

Notes

• branch b-rtd-c-extensions

Problem

At the moment everybody formats his code as he pleases himself. If many people should work together on this project, then there needs to be a common style guide.

Solution

I'd suggest to use PEP-8 and/or the HidaV style guide as foundation for it.

We should also provide related configuration files for pylint and/or other useful tools to make automated validation possible.

Notes

Changes are in branch f-codingstyle.

Problem

The vision reflects my personal ideas from maybe half a year ago. Now the number of people interested in MONK grew and even my ideas have changed since. It's time for an update.

Solution

The part needs to be rewritten and discussed with the other MONKers.

Problem

At the time of this writing it is not possible to create a second device.Device object with MONK, because while creating a serial connection, the Device currently assumes that it's serial connection will always only use it's default parameters, which then call the environment variable. Because the first serial connection from the DeviceTestcase already uses that connection it can't be created a second time.

Solution

There are many solutions to this problem. Some options:

1. Add a serial configuration variable to the device types and device.Device.__init__() processing.
2. Add a meaningful way to Device to call alternative connections, which will be created up front.

Notes

None

Problem

I guess that I am able to finish the coding guidelines in the next few days. After that it should be possible to release 0.1.1.

Solution

To solve this Issue, the following things need to be done:

• check all TODO's and Issues for 0.1.1 if they are completed
• complete all open issues
• create and tag a release candidate
• make sure all version strings are up to date
• update the requirements-*.txt files
• present the RC at a Stammtisch to recieve the ACK to proceed
• merge the accepted release candidate to the master branch
• check and update RTD and Travis
• push newest version to PyPI

Notes

• branch v-0.1.1-rc

Problem

A lot of hardware dependent context is inside the MONK classes. It should be separated and extracted from MONK to allow users without DFE Hardware to make use of MONK.

Solution

To be discussed.

Situation

There are some differences between our development environment and the ReadTheDocs environment, which lead to the pictures not being scaled correctly. That in turn makes the start page of our documentation rather ugly.

Solution

Resize the pictures themselves to match the website borders. Then no scaling is needed.

Notes

Problem

Sphinx does look for MONK at MONK/src/monk_tf instead of MONK/monk_tf. This change was introduced by #34. Sphinx was simply forgotten

Solution

Change the reference in the doc/Makefile and doc/source/conf.py. If it changed correctly, then building the documentation should work without errors or warnings.

Notes

• to review this issue, look if the docs build correctly:

     # somewhere in your filesystem
     somewhere$ git clone -b b-tell-sphinx-no-src [email protected]:DFE/MONK
     somewhere$ cd MONK
     MONK$ virtualenv .
     MONK$ . bin/activate
     (MONK)MONK$ pip install -r requirements-develop.py
     ...
     (MONK)MONK$ python setup.py develop
     ...
     (MONK)MONK$ cd doc
     (MONK)doc$ make html
     # no errors or warnings? -> ACK
     # optional, not really necessary:
     (MONK)doc$ chromium-browser build/html/index.html
     (MONK)doc$ deactivate
     doc$ 
  

• @binschek found an error you might look for here:

  (MONK)[binschek@cd-400-548 doc]$ make html
  rm -rf build/html/*
  rm -rf source/monk_tf.rst
  rm -rf source/modules.rst
  sphinx-apidoc -o source ../src/monk_tf
  ../src/monk_tf is not a directory.
  make: *** [apidoc] Error 1
  (MONK)[binschek@cd-400-548 doc]$ 
  

  • branch b-tell-sphinx-no-src

Problem

Using this simple example code (e.g. in main() of ssh_conn.py) with an existing myfile

host = "myhost"
login = ("myuser", "mypassword")
ssh = SshConn(host, login)
myfile = open("myfile")
ssh.put(myfile, "/tmp/myfile")
del ssh

leads to an exception

Traceback (most recent call last):
  File "ssh_conn.py", line 154, in <module>
    main()
  File "ssh_conn.py", line 150, in main
    ssh.put(myfile, "/tmp/myfile")
  File "ssh_conn.py", line 139, in put
    chan.close()
  File "/usr/local/lib/python2.7/dist-packages/libssh2/channel.py", line 53, in close
    return self._channel.close()
_libssh2.Error: Unable to close the channel.

It seems that the implementation of SshConn.put() is not functional.

Solution

tbd

Problem

@DmsPeterWinkler found that a TestCase using MONK died with

Error: Unable to close channel

in line 85 from ssh_conn.py

Solution

instead of a simple close() use error handling:

try:
    chan.close()
except:
    chan.wait_closed()

Notes

• branch b-ssh-dies
• for reviewers:

  • you can run the test suite with all tests like that:

    # preparations
    $ git clone -b b-ssh-dies [email protected]:DFE/MONK
    $ cd MONK
    $ virtualenv .
    $ . bin/activate
    $ pip install -r requirements-test.txt
    $ python setup.py develop
    # the actual test suite:
    $ python setup.py nosetests
    # no test should fail
    # also have a look inside test/test_ssh_conn.py