search

WebMemex / webmemex-extension

📇 Your digital memory extension, as a browser extension
https://webmemex.org
Other
208 stars 45 forks source link

Implementation of a Testing Suite and Continuous Integration Pipeline #103

Closed reficul31 closed 6 years ago

reficul31 commented 7 years ago

This is the testing project for Google Summer of Code 2017. This project aims to setup a testing suite and continuous integration pipeline for the webmemex extension.

For the project, the testing team has decided to use the Jest framework written by facebook. To have a look at the mock testing suite(branch) build during the community bonding period.

Issue List

Student:
Shivang Bharadwaj / @reficul31

Mentors:
Jonas Aschenbrenner / @sanjo
Dan Lüdtke / @danrl
Stefano Solinas / @obsidianart
Raj Maurya / @raj-maurya

Proposal:Link
Blog:Updates
Issue List:Issues
Branch:Work WiP:Pull Request

Treora commented 7 years ago

Great! Thanks for taking this initiative, having tests would be splendid. I imagine that for some parts you may want to understand better how and why things work. Feel free to contact me to ask (e.g. ping me on IRC), and we could also use the answers to better document the code as we go.

As for your schedule, some parts are still so volatile that it may be too early to write tests. I would for example advise to skip the writing tests for the browser history import for now, as that is unfinished and unused (a new history import system is being actively developed by @poltak for WorldBrain, see WorldBrain#25).

Shall we perhaps have a call one of these days to align our development plans?

reficul31 commented 7 years ago

@Treora Yes, I would be happy to oblige to a call with the whole team so as to align our plans and so that our project doesn't get into the way of what other people are working on. As for the schedule I will look into the current issues and PR which are unfinished and modify it right now.

I imagine that for some parts you may want to understand better how and why things work. Feel free to contact me to ask (e.g. ping me on IRC), and we could also use the answers to better document the code as we go.

Thanks for all the help. I will be sure to reach out to you in a day or two.

reficul31 commented 7 years ago

Documentation

@Treora @Sanjo This is in reference to the documentation of the project and all the other spinned off repos. Recently I have been looking a bit deeper into documentation of the code base. At first I was thinking of having a wiki as developer docs but as @Sanjo mentioned, it would be too difficult to change the docs for when any new code is added. So, for now I have been looking into making a repo inside the project named docs like django does here. Obviously the implementation of the django project is far different from ours but I really liked their setup including sphinx and rst. I would like to clear some things up with @Treora regarding the documentation.

How to document?

As I have mentioned I have been looking into the various ways in which the documentation could be setup. Any thoughts or suggestions @Treora @oliversauter @Sanjo?

What to document?

This is a weird question as it is pretty easy to answer, but necessary all the same. I was thinking along the lines of documenting the API of each module and explain how each module has been used. Having a function prototype to explain what arguments are passed to it etc.

Where does the docs go?

Where do I put the docs? In the repo? On github pages?

Should guides be included into the documentation?

Guides of how to setup the development environment and start contributing, building the extension in firefox and for chromium.

In-code documentation?

In-code or in-source documentation(not an official term) is a form of documentation where a part of the docs are placed in the src code to help guide the developers. I really like the golang approach in which each function definition is prepended by a small descriptor.

I would love to try the suggestions given here on the smaller repos first(freeze-dry) and then move onto the main repo.

Treora commented 7 years ago

Cool that you're getting to this. I would keep documentation inside the repo, among the code folders or perhaps (some of it) in a /docs folder. We are not big like django, it seems better to me to keep things together and keep it easily maintainable. I would use tools if they really add value and don't add maintenance effort, but I think plain text or markdown files would be fine for this project. But play around with tools if that's what makes you happy. :)

I would probably start with a few lines of explanation above every function (in jsdoc syntax). These may contain notes, warnings and todos for developers; realise we are not documenting a library or framework, but mainly code that is used internally. Explanation of the purpose of all functions/code in a file can be added at the top of the file (a bit like util/webextensionRPC has it now).

Guides to help developing would be good, the readme contains a bit of this, but feel free to improve it. Also I once made this code tour to explain the high level code organisation, which could be modified/moved/removed if we create other forms of documentation.

Treora commented 6 years ago

Closing this issue. Last summer is definitely over by now. :)