3.3 KiB

Raw Blame History

Contribution Guide - How to Setup Environment

WARNING - 19 Apr 2020 - The below creates an environment where you can successfully run the tests

However it still needs testing again; and also needs worked example on actually contributing 'value' and not putting noise back into the repository!

Whilst using Diagrams is easy and some folks will find setting up and extending Diagrams easy - for others with Python, Bash and Go dependancies it is harder...

So a worked guide to setting up a VM with linux so you can contribute to Diagrams.

Thanks: Thanks to ViktorOrda for assist on getting this to work.

This guide was written using ubuntu 18.04 on Azure.

VM

Easiest and cleanest way is to boot a new Linux VM on your cloud provide of choice.

16 GB HDD is more than enough
2 GB Ram is more than enough

Required Software

To contribute to Diagrams you will need the required software (all installed from command prompt):

Update apt (so you can find stuff)

    sudo apt update

Python - You want version 3 (Diagrams needs this)

	python --version

If this returns a 2.7.x type number you are going to have to check python 3 is installed; You need Python 3.6.x

	python3 --version

If Python3 does not return a suitable version you will need to install Python3.

    sudo apt-get install python3

Then to make sure the Diagrams autogen.sh script will work correctly we need to make the alias for 'python' to map to python3. To make python3 the default run this:

 sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10


    NOT: sudo update-alternatives  --set python /usr/bin/python3.6

Or Google 'how to alias python3 to python' and similar to get into the whole aliasing topic.

pip (to make your life easier) - will probably report already installed.

   sudo apt install python3-pip

   sudo apt install git

Go
- Security warning (hence --classic) and hence why use VM

   sudo snap install go --classic

Black (used by autogen.sh)

   pip3 install black

NOW DISCONNECT from SSH and reconnect (to reset your environment path otherwise Black won't work)

Requirements as per Contributing page

Round

    go get github.com/mingrammer/round
    sudo cp go/bin/round /bin

Inkscape

   sudo apt install inkscape

Convert

   pip install convert

Grab the Diagrams Code

  git clone https://github.com/mingrammer/diagrams.git

To Run the Autogen

  cd diagrams
   ./autogen.sh

Actually Building the solution and installing diagrams; getting tests to pass

Whilst ./autogen.sh works the tests don't (because Diagrams isn't actually installed yet) and also as Diagrams isn't installed you can generate any pictures i.e. test your contribution So some more things to install before you can run Diagrams.

Be careful here as you will create folders in the diagrams folder that you don't want to contribute back into the repository!

    sudo apt-get install graphviz
    sudo pip install poetry
    sudo apt-get install python3-venv
    poetry build
    poetry install

Now from the diagrams folder run:

  python -m unittest tests/*.py -v

and all the tests should pass.

3.3 KiB Raw Blame History