Identify major issues that make contribution to code hard

[tintinkerer]

Contribution in what sense? Contributing to the code, to the learning material on the site, to the issues highlighted on Github? Please provide a description so we can understand the scope of this issue.

[kantord]

@libsoc in this issue I'm referring to contributing to the code. There will later be another about contribution to the course material

[StCol]

I would say a major obstacle is lack of specificity. Maybe mentioning specific files/folders where help is needed related to specific functions can help other developers speed up the comprehension of the overall project's structure

[kantord]

@StCol do you have some suggestion how and where it would be ideal to specify that?

[StCol]

@kantord For example, you have an open issue about 'fun/interesting facts about the language' however it does not specify where/when you want this to be displayed therefore even with ideas for the content it is difficult to know where to append it

[decentral1se]

Yeah basically, I see no obstacles to contributing except what @StCol mentioned about not having tickets that are easy to follow. However, I suppose that is totally normally when all the ideas and concepts are trapped in your head in the early stages :) We will keep asking :)

Btw, I was able to setup a dev environment in 15 minutes. That is good.

[kantord]

Yup, I was trying to make sure it's easy to set up the dev env! That would be the worst thing to lose contributors over :sweat_smile:

I am trying to define tasks better, but it actually takes a surprising amount of time.

Also, I want to properly document what's what in the project directory and where things should be put (it's also some refactoring work, because clearly it's not structured enough currently)

[decentral1se]

I am trying to define tasks better, but it actually takes a surprising amount of time.

Understandable. I suppose it's easier to discuss things on the IRC/Matrix side since there is so much info to be gotten through. Anyway, that's a good step! Thanks.

[kivutar]

Setting up the frontend with yarn was very easy.

Customizing the CSS style of the course took me quite some time, I had to learn a bit of svelte and bulma, but even then, the styles are a little bit all over the place (which is the current trend is modern UI).

Changing the font and the color palette was super easy for instance. But making all the buttons rounded and flat took me more than 20min.

I really like the fact that svelte builds is a static website. It will certainly ease the deployment. Although I'm not sure if this is a goal for this app to be deployed in a ton of different places. It might prevent you to build a centralized community if the instances are spread.

When setting up the course editor, pipenv did complain that pg_config wasn't there. I had to setup postgres. Even if I did set DATABASE_URL=sqlite:///db.sqlite3

On OSX, I had to specify python3 to be able to run python3 manage.py migrate. Then the app complained that ModuleNotFoundError: No module named 'django'.

I finally understood that I had to be in a pipenv shell. The phrasing You can now drop into a Pipenv shell so that you can make use of the dependencies you installed. was a bit misleading, I thought that I had the choice to do it or skip it.

There is no dumps/courseData.json in the repo, it's in fact in ./workspaces/web/dumps/courseData.json.

yarn export did work well.

So, no big issues with setting up the dev env. I could get everything running in 1h, taking the time to play with the course and read a part of the source code. I hope the documentation can be improved a bit based on my comments.

The course editor looks cool. I think that Django is a good choice for this.

[kantord]

Customizing the CSS style of the course took me quite some time, I had to learn a bit of svelte and bulma, but even then, the styles are a little bit all over the place (which is the current trend is modern UI).

I am considering refactoring this. Essentially I want to put all the UI components into lluis, and each component would have it's own styles. Not sure what you think about this solution. The reason why I want this is this:

• We could retire bulma as a dependency
• We could use CSS variables for customization (dark mode for example)
• There would never be unused styles rendered on the page, because each component would come with their own styles
• It would be easy to find where to change styles, the styles would entirely be in our repo, and always in the same place as the rest of the code for each component

However, I feel like it doesn't solve the problem you mentioned: basically customization that isn't controlled by CSS variables would stay difficult.

What do you think about the approach overall though?

[kantord]

I really like the fact that svelte builds is a static website. It will certainly ease the deployment. Although I'm not sure if this is a goal for this app to be deployed in a ton of different places. It might prevent you to build a centralized community if the instances are spread.

There would probably always be one instance, although I can imagine companies orNGOs setting up their own instances for internal use. For example: training immigrant workers on language skills of daily importance at work. Or the same for refugees.

[kantord]

Also people can set up their local instance if they want to avoid any network functionality. I'm planning to create a package for that that would be easy to install.

[kantord]

When setting up the course editor, pipenv did complain that pg_config wasn't there. I had to setup postgres. Even if I did set DATABASE_URL=sqlite:///db.sqlite3

Could you please create a separate issue for this one :pray:

[kantord]

On OSX, I had to specify python3 to be able to run python3 manage.py migrate. Then the app complained that ModuleNotFoundError: No module named 'django'.

This is probably an issue with the documentation, I never tried but I think with pipenv it should work fine, no?

edit: yes, exactly as you said.

If you have time, you are very welcome to create an MR with these documentation fixes.

[kivutar]

What do you think about the approach overall though?

Having per component styles is the current good practice in the modern UI world, where apps are huge and modified by large teams. It avoids the problem of regressions across components.

Of course it has downsides, for example, themes. If you take this approach and want things to be customizable, you end up implementing a theming system in JS. CSS being itself already a good theming system, it's feature duplication.

The alternative is to choose a base like bulma, and apply a small set of pure css overrides on top of it. This is only viable if your app plan to stay small and have a finished set of simple components. It works for websites like Wikipedia. It doesn't work well on ever expending designs.

[kivutar]

@kantord This issue is preventing me to contribute a course: https://github.com/kantord/LibreLingo/issues/625

[kantord]

@kantord This issue is preventing me to contribute a course: #625

@kivutar, there's more to it. Actually, the course data is not meant to be managed by git at all. It's managed by Django Admin over a postgres database. The repo does contain a dump of this database (without user data), so that people who fork the repo are able to it up. It also contains the exported course.

What is really preventing you from contributing to the course is that you have no access to the hosted course editor yet. (It needs improvements before it can get public access)

Also, you can't export from the production course editor because you have no SSH access to it.

It's a priority for me to remove these hurdles from contribution, but we're not there yet.

[kivutar]

@kantord Oh, but I was able to run the course editor locally.

I started adding a French from English course.

I just have no idea how to export it to become available in my local frontend.

Do I have to use django-admin dumpdata?

[kantord]

@kivutar yes, you should be able to run it locally, however that's a separate instance of the course editor. It doesn't sync with a remote server. What you did if what you should do if you want to try things out locally or if you want to set up a fork.

There is no "official" way of exporting the course locally, but you should be to do everything that you need, for the Spanish course. For French courses (or any other language basically), there is at least one missing component: the audios.

This is the script that you have to extend if you want to add French audio support: https://github.com/kantord/LibreLingo/blob/master/workspaces/web/scripts/fetchAudio.sh Keep in mind that you'll need to set up Amazon Polly locally, or find another way to source the audios.

Here's how you'd export a course locally:

• pipenv run python manage.py exportcourse $COURSE_ID this would export a course from your local database into the JSON files: all the skills you've added should appear.
• yarn fetchAudios to fetch missing audios (you have to export the course first!)
• yarn fetchPhotos this will fetch missing photos

This could probably be documented better :-)

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.