Add run-qa-check script, make sure it includes the 404 link check we have in openwisp-website and openwisp-radius, eg: https://github.com/openwisp/openwisp-radius/blob/master/run-qa-checks#L10-L16

First of all, you should be able to replicate this feature in your own development environment.

How to do that is roughly explained in this mailing list thread: https://groups.google.com/d/msg/openwisp/xVZR7vy1kck/OQzzD8OfAgAJ

Take notes while you try to do it.

Once you are able to have a device automatically connect to the VPN after registration, use your notes to create a new page in the user documentation.

Document the following concepts

• VPN automation what's for
• VPN templates
• explain what happens when a VPN template is flagged as default
• explain the "auto client certificates" feature
• explain how to install a VPN server with ansible and how to import the VPN server configuration into OpenWISP (explain also that this is not automated yet)

Once ready, send a pull request and follow up on our reviews.

Document how to install openwisp-config on a LEDE virtualbox instance and connect it to OpenWISP 2.

In http://openwisp.io/docs/general/help-us.html there is

3. Stars on github
3. Documentation

So I had a task where I had to a vm with OpenWRT and connect it to OpenWISP locally. There were some challenges that I faced and here's a list of what can be improved so that other students/people don't get confused and know exactly what to do.

1.) I couldn't get the network to work in my OpenWRT vm.
refer to: https://openwrt.org/docs/guide-user/virtualization/virtualbox-vm
For the second adapter, it wasn't mention what to use. I was using the PCInet-III or something instead of the Intel Pro (82540EM)
I thought it would be good to let you know so that future individuals don't face this problem.

2.) Oh and for the allocation of , it would be better that on this tutorial if it was set to 192.168.56.3 (more than 192.168.56.2 as it is used for the OpenWISP Server).

3.) After setting up everything, I found out that no devices were being created on the local OpenWISP website.
I had the message "openwisp: OpenWISP config agent started" but there was nothing on the website.
I later found out (thanks to reza) how to fix all that. Some info on: http://openwisp.io/docs/user/configure-device.html need to be improved as there is some confusion. Firstly lines "option uuid" and "option key" should be commented I think, secondly it would be great if it was mentionned that if we had our OpenWISP server locally (e.g 192.168.56.2), then the "option url" would be 'https://192.168.56.2'. That is more beginner-friendly as they know what to write, if should be mentioned and if whether ".../admin" should be written or not.

Otherwise everything is great! I am not saying that anything was bad. On the contrary, the tutorial is really awesome! I am just suggesting how it would better, that's all!

The mentioned python(book) resource link under Programming languages and frameworks: is dead and need to be replaced.

Add a page in the openwisp documentation where we provide the following information:

• links to presentations (including slides and videos whenever possible) about OpenWISP (look on Google, ensure presentations from PyCon, OpenWRT Summit and FOSDEM are present)
• links to popular blog posts mentioning OpenWISP (look on Google)
• a section with links to logos and graphic material
  • OpenWISP Logo Black Foreground
  • OpenWISP Logo White Foreground

Reserved for GCI

Explain how to use configuration variables and the default device context variables described here: https://github.com/openwisp/django-netjsonconfig#netjsonconfig_context

Please ensure to have dedicated time understood

Changes addressed in #87 and #83 are not reflected on the website.

Document what is described in this mailing list thread: https://groups.google.com/d/msg/openwisp/nk7p6H5JXLU/5Ey6b5ffBAAJ

We need a comprehensive documentation which describes all the modules.

I want to avoid having the documentation of each module contained in this repo because that would make it harder to maintain: if we keep the documentation of each module in the module itself, we will be able to always request contributors to document their work because it will be easy for them.

We could use a system of git submodules, each OpenWISP module will be a submodule in this repo and we'll have some scripts which will glue everything together and generate the sphinx documentation.

The documentation could be divided as follows:

• user documentation (quickstart, guides, explanation of features)
• developer (information for developers and contributors)
• general (project goals, values, press, etc)

The user and developer sections will then have one sub-directory for each module, or something similar.

Each module could have a structure like the following:

# user:
/openwisp-controller/docs/user
/openwisp-controller/docs/user/feature1
/openwisp-controller/docs/user/feature2
# docs:
/openwisp-controller/docs/developer
/openwisp-controller/docs/developer/setup
/openwisp-controller/docs/developer/extending

The Makefile will take each module user and developer directory and copy the files as follows:

cp /openwisp-controller/docs/user/* /openwisp2-docs/user/openwisp-controller/
cp /openwisp-controller/docs/developer/* /openwisp2-docs/developer/openwisp-controller/

@xamfy, @HargovindArora right now we have two pages that seem redundant, we need to merge them.

Glossary has a nice structure and we should keep it that way, we could add some of the content in "Technologies Involved" which is missing from "Glossary", then I'm not sure which of the two titles is better, I really don't have a clear idea now, but for the moment we can focus on merging the contents, can you do this?

We need to have a page in which we introduce our contributors to the python and django world, eg:

• explain the advantages of using python
• provide 2 links to get started with python 3
• explain the advantages of using a framework like django and django-rest-framework
• provide links to get started with django and django-rest-framework
• link and provide a brief explaination of the development tools we use:
  • ipython
  • ipdb
  • django-extensions
    • shell_plus
    • runserver_plus
  • django-debug-toolbar
• provide an example of how to enable and use those tools in one of our modules, for example openwisp-controller

In the past we had runflake8, runisort scripts all over the repos.

Now we don't have any script but I realize we may need to reintroduce a script for each repo because the flags passed to openwisp-qa-checks are slightly different for each repo.

This way we can have a run-qa-checks script for each repo and we can create pre-commit-hooks that run the script before each commit.

We can put the hook in each repo automatically as well as suggested here: https://stackoverflow.com/questions/3462955/putting-git-hooks-into-repository

The hook could be saved in openwisp-utils. Python packages could install it automatically in the setup.py script, eg:

• if the current directory is a git repository and if pip install -e . is being called from within the project itself (eg: check the setup.py script and look for something unique in it)
• then copy the pre-commit-hook from openwisp-utils and install it / symlink it, whatever

For non python packages we can do something similar as all the repos should have some kind of build/install script/procedure (if they don't have one, we must add one).

Some objects can be shared among multiple organizations, like Templates and VPN servers, they just need to have the organization set to nothing, but this is not explained anywhere.

We are soon going to integrate all repositories with Taiga. We need to make sure that we change the way we write commit messages accordingly. These changes need to be reflected in documentation too.

Following articles explain the way Taiga attaches to commits

1. https://tree.taiga.io/support/integrations/changing-elements-status-via-commit-message/
2. https://tree.taiga.io/support/integrations/attach-commits-to-elements-via-commit-message/

While making any change to any file, it often happens that code editors introduce unnecessary changes in the code like extra spaces or new lines.

Mention some guidelines for contributors to tell them what editor to choose or what configurations should be done in the editors so that unnecessary changes are not introduced.

Also, mention the coding style used by org and respective tools used like Flake and everything else!

Just like we do in django-freeradius see:

• django-freeradius/.travis.yml
• django-freeradius/runsphinx-build

In order to semi-automate the work needed for creating general release notes (#108), I think we should switch to https://www.conventionalcommits.org/

I would keep the prefix between square brackets as we do now, but use the words indicated there which would help us to generate the release notes.

Blocked by openwisp/openwisp-utils#110 and #109 (these two issues have to be tackled first).

We should enforce the maximum line length of each rst file to 75 characters because this makes editing multiple files in split editor mode or in split terminal vim windows much easier which in turns increases productivity.

I have no idea yet how to do this, I hope there's some tool available that does it.

Once this is done, it should be added to the travis build mentioned in issue 28.

@HargovindArora we need to have something like this:

• https://github.com/battlemesh/battlemesh-test-docs/blob/master/README.rst
• https://github.com/battlemesh/battlemesh-test-docs/blob/master/requirements.txt

We should give a name to the releases and write clear release notes for each release.

The release notes of each module may be used as a base for creating release notes.

We may change the way we write our change logs in order to semi-automate this.

Possible reference: https://itnext.io/automate-your-releases-versioning-and-release-notes-with-semantic-release-d5575b73d986

Found some more useful tools:

• https://github.com/semantic-release/semantic-release
• https://github.com/relekang/python-semantic-release

A well-structured guide has to be prepared so that first-time contributors can know the do's and how's of contributing to this very organization.

A documentation or glossary has to be created for developers so that they can start off quickly in setting up the project.

A guideline for newcomers has to be set up so that they can understand how the project's different components are linked together.

we need a style convention section in which we describe our coding style conventions:

• commit message style (this is explained in the contributing guidelines but the section is not titled properly and I guess not many people are reading it)
• python code convention
• javascript code convention
• openwrt related code convention

See openwisp/openwisp-utils#94 for more information

We do not use runflake8 and runisort scripts anymore, we now use ./run-qa-checks.

This section should be updated: https://openwisp.io/docs/developer/contributing.html#coding-style-conventions

I've been repeating this too many times now:

If you need help in solving problems, using the chat is better, but if you want to discuss important implementation details or ask detailed questions regarding a specific openwisp module or feature using the mailing list is better for several reasons, but the best reason is that all discussions are indexed on search engines and easily retrievable in the future, so the mailing list over time become some kind of fall-back documentation archive which is very good for any open source project.

We need to find a good place in the docs to explain this.

A project structure guide has to be set up that lists the structure of the various projects in this organization.

Create a new page in the user documentation that explains the following:

• what is a configuration template
• mention (and link) NetJSON and netjsonconfig
• provide at least 3 example templates for OpenWRT, you can take some from the netjsonconfig documentation
• add a link to this new page at the end of the configure-device.rst to make it easier for users to find it
• don't forget to add the page to the main index so it will be listed in the main menu of the documentation website

After Doing Everything, At Last Step To Make HTML It Shows That, bash: make: command not found
Any Fix. What Should I Do

We need a simple code of conduct which clearly states that any type of racial, religious or sexual harassment as well as ad-hominem attack is not tolerated in our community.

A good example is https://www.djangounderthehood.com/coc/ although we need something simpler.

We clearly need to state that anyone who will breach these rules will be kindly asked to leave the community or forcibly removed if they continues in assuming behaviour that goes against our values.

Contributors should try to send 1 PR for 1 feature.
If they are working on a PR that touches a group of related features, they can work on it in 1 PR if they prefer, but have to have 1 commit for each feature they change/introduce/remove.

Maintainers can work on branches and open PRs to merge various changes in one branch.

Once openwisp/openwisp-controller#340 is merged and the new version of ow-controller is released.

LEDE has been merged back in OpenWRT, we can update the docs and remove any mention to it.

Note: the configure-device.rst page needs to be updated accordingly, including the download URLs.

A documentation guide has to be created to tell the contributors and newcomers that which technologies and architecture have been used up in this project and organization as well.

Document how to use the template tag feature.

We can improve gitignore by adding virtual environment directory in ignore list. We can use tools like gitignore.io to generate gitignore file.

Add a page in which we collect presentations that talk about OpenWISP 2, different languages are allowed, each language will have its own section.

This is a kickstart for the documentation effort spawned on the mailing list.

Obviously the only supported way of installing openwisp2 should be the ansible playbook.

At minimum there should be

• How to install ansible + ansible galaxy (link to external documentation)
• How to install role from galaxy (link to external documentation)
• Setting up the inventory
• Setting up the playbook
• Introduce default variables for playbook (mention they exists and list them)

It would be great to have a tutorial that explains how to:

• setup a configuration template that creates a mesh network with 802.11s and OLSRd2
• mention encryption if needed
• explain how to configure the network topology module to collect the topology information using the RECEIVE strategy, it's documented in Italian here: http://wiki.ninux.org/TopologyVisualizer (the script can be installed on the device with an additional template)
• explain how to see the network topology graph
• mention daily historic data is collected and can be viewed

In the future we could have more variants for 802.11s and Batman-adv, 802.11s and Babel, 802.11s and BMX7.

I will add the following sections in the near future:

• What are the values which the founders had when they created OpenWISP?
• What other values were brought in by further contributors?
• Where is the community heading to?

We're adding openwisp-qa-format and a way to force the commit message check in openwisp/openwisp-utils#89, we should update the docs to mention these two tools and suggest their usage.

The line length check should return all errors, now it's stopping at the first found.

In code samples we should allow a higher length of lines, I think 114 is good.