Documentation for absolute beginners to software development

[lb-]

During recent Outreachy and Google Summer of Code application periods we have seen that many developers are keen to get started with Wagtail but have essentially zero prior experience with setting up their machine for development.

I'm not sure that we need to provide all the details for this but do think we have a gap in two ways. The first being your first Wagtail site page and the second being for new contributors.

Areas

Area 1 - Your first Wagtail site.

https://docs.wagtail.org/en/stable/getting_started/tutorial.html

Area 2 - Your first Wagtail contribution

https://docs.wagtail.org/en/stable/contributing/developing.html

At this point we can expect the developer to have done the Wagtail site tutorial maybe?

• https://github.com/wagtail/wagtail/#-contributing
• https://docs.wagtail.org/en/stable/contributing/index.html
• https://github.com/wagtail/wagtail/wiki/New-contributor-FAQ
• https://wagtail.org/blog/5-simple-ways-anyone-can-contribute-to-wagtail/
• https://wagtail.org/blog/ten-tasty-ingredients-for-a-delicious-pull-request/

Area 3 - Core team reviews and feedback

• https://github.com/wagtail/wagtail/wiki/PR-triage
• https://docs.wagtail.org/en/stable/contributing/issue_tracking.html
• https://docs.wagtail.org/en/stable/contributing/committing.html

High level assumptions

• Windows development
• Base installation, no Python, no git, no editor, no WSL
• Having written essentially no code, little to no awareness of Python
• Zero awareness of Django
• Opinionated guide expected (what should I do, not what are there ways I can do it)
• ... Others (write in the comments)

Useful examples of similar documentation

• Interactive Git branching guide https://learngitbranching.js.org/
• https://github.com/carltongibson/djangocon-sprints (Django sprint resources, lots of help for getting started)
• https://docs.djangoproject.com/en/dev/intro/contributing/ (Django - writing your first patch guide)
• https://zulip.readthedocs.io/en/latest/contributing/contributing.html (Zulip has some incredible documentation for new developers)

---

I'll add thoughts on solutions in the comments.

[DokuaAsiedu]

For Windows development, contributors might need a package manager like Chocolatey to download the make utility in order to run commands like make html if they encounter this error: make is not recognized as an internal or external command, operable program or batch file

[lb-]

There is also this issue that has some notes about similar Windows development problems #4870

[Dev-Liz]

Based on the High-level assumptions stated:

Area 1 - Your first Wagtail site.

- 1. Prerequisites such as:

• Operating system
• Knowledge required
• Tools etc.
  Should be listed. And links to the necessary resources should be provided.

- 2. There should be a note stating the difference between each python command for different OS

**- It should also be stated that a python version (e.g python3) is used when a user has more than one version of python installed. But for a person installing python for the first time, using just Python is fine **

• Expected behaviors such as hidden passwords during Createsuperadmin should be stated.

• Also, I think the expected outputs when running the commands on the guide, should be included. So newbies can use them to verify their own processes.

Area 2 - Your first wagtail contribution

This should be a complete tutorial guiding the user by hand, on how to make their first contribution. From the first step to the last.
New contributors can replicate this process, then feel more confident to begin their own contributions.

[lb-]

Added some links

Interactive Git branching guide https://learngitbranching.js.org/
https://github.com/carltongibson/djangocon-sprints (Django sprint resources, lots of help for getting started)
https://docs.djangoproject.com/en/dev/intro/contributing/ (Django - writing your first patch guide)

[lb-]

See also - bakerydemo issues with the development docs there wagtail/bakerydemo#363

[thibaudcolas]

See #9523 – suggestion for us to have a FAQ page with common setup issues, like WordPress does.

[lb-]

Note - this PR starts a bit of this section in the development guide. #10080

Thanks @Lovelyfin00

[lb-]

See issue and PR for better development docs for windows (a great start).

#9540
#9559

[albinazs]

I personally struggled while trying to connect my local Wagtail fork to the bakerydemo without deep knowledge of Python and virtualenvs. I tried "easy" ways but can't really recommend them:) The Docker setup was not working for me in a stable way, Vagrant was not an easy option with my hardware (issues with the VirtualBox version for Mac with Apple chip), and GitPod was not an option at all:)

It would be nice to have a step-by-step beginner guide to connect those two (local fork + bakerydemo) using Python scripts only. It would be invaluable for front-end contributors.

[cnk]

My local civic hacking group gets a lot of first time contributors so has very detailed docs on dev machine setup and on how to use GitHub. We could probably use their docs as an outline and then add information about python and virtual envs.

[Lovelyfin00]

Your first wagtail site

• For those that just installed Python for the first time, I think it should be noted that they should check if Python has been added to the path in their Environment Variables. This is because, during the installation process, they might have mistakenly unchecked the option of adding Python to path.
• In the first note section where the link to the guide for installing the libjpeg and zlib libraries is, it should probably be written that python3 can be replaced with py because, during my installation process, I had issues with that. I had to use the python command as opposed to what was written in their documentation.
• Video explanation on setting up the first wagtail site would be super awesome. I used this tutorial on YouTube during my installation and it really contributed to increasing my understanding and familiarity with Django and Wagtail.

Your first Wagtail contribution

• The first thing I would love to point out here is that the documentation is still saying that a copy of Wagtail should be cloned. I mean, to make it easier for new developers, it would be better to say that the Wagtail repo can be forked and then the forked copy can be cloned. This would make it easier with making contributions.
• Before the second code block that assumes the virtual environment is already created, it would be nice to include a link to the section in the Your first Wagtail site that shows the method of setting up the virtual environment.
• After setting up the development environment, a link to the different GitHub repos on setting up bakerydemo should be included in a prominent place. So that they should know that that's the next thing to do after the development environment set up.

[lb-]

@Lovelyfin00 - feel free to raise a PR to the docs with these suggestions.

[lb-]

PR up thanks Loveth #10080

[xomcodes]

Your First Wagtail Contribution

I think it would be nice to state that the Wagtail core code repo should be forked first and then cloned to make things easier because I ran into a couple of git issues just cloning the repo

[lb-]

@xomcodes I have attempted to address this in the WIP new contributors guide - feedback would be great.

#10070

[dchidindu5]

Here's the link to the windows installation guide for wagtail @lb-

https://docs.google.com/document/d/1Z-PrHrpL7qSmeUjsL-SEKoztgviK9s4N8N_G8HADI5A/edit?usp=drivesdk

[lb-]

Thanks!

[lb-]

I think we should somehow call out that other projects in the Wagtail ecosystem can accept contributions. These projects may not get the same attention though but it's also a good way to start.

• Bakerydemo
• Sphinx docs theme
• Wagtail.org
• ...

[Julietadeboye]

Blog post to help windows devs manually set up bakerydemo and wagtail
https://juliet.hashnode.dev/a-step-by-step-guide-for-manually-setting-up-bakery-demo-with-wagtail

[lb-]

Thanks @Julietadeboye - I will include a link to this in the draft new contributors guideline
#10070

Also - we have since added this to the third party tutorials listing.

[dchidindu5]

@lb-
I'm writing a how to guide on how to get started with sphinx_wagtail_theme.
I'll publish it as soon as it's done

[lb-]

awesome

[AnishaSingh0118]

Your first Wagtail site.

• Wagtail command not found error

Fixed it: by adding py dispensary.
If erros persists delete the previous py version.

Your first Wagtail contribution

• Set up does not run directly with React/js

Fixed: by installing Docker and Vagrant.
But here is a catch, there are only specific versions that needs to be installed for the set up to run properly.

• Regarding npm ci command (is confusing)

Fixes: in documentation CLI command is mandatory which should be avoided and can provide options for setting up, eg: " make start", "npx" or VS code should be there.

• Tests are not proper

Fixes:

1. Should make use of lint fix manually.
2. Provide links for latest version of VM, Vagrant, Docker.
3. Only py tests are not enough should make use of kubescape/ kubernetes & puppeteer tests.

[dchidindu5]

Ok sir I'll look into it

…

On Tue, Nov 22, 2022, 12:25 PM LB (Ben Johnston) ***@***.***> wrote: There is also this issue that has some notes about similar Windows development problems #4870 <#4870> — Reply to this email directly, view it on GitHub <#9557 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEPEES55UAU6BQQ2KOQSWR3WJSUS5ANCNFSM6AAAAAARTODVAI> . You are receiving this because you commented.Message ID: ***@***.***>

[lb-]

General update

Where possible, I have included feedback from this discussion into the draft new contributor's guidelines here #10070

Any feedback is welcome.

I have not made that guide focus on the very low level technical items (such as debugging python path on Windows) but hopefully it's a good level of detail with links to the other parts of the Wagtail docs that you need to read.