[{"element_type":"markdown","content":"\u003ch1\u003eUsing Github Codespaces for CircuitPython Development\u003c/h1\u003e\n\n\u003ch2\u003eIntroduction\u003c/h2\u003e\n\n\u003cp\u003eIf you wan't to contribute to CircuitPython, one of the hurdles you need to\ntake is the installation of the development environment.\u003c/p\u003e\n\n\u003cp\u003eThere is a nice guide from Dan Halbert\n\u003ca href=\"https://learn.adafruit.com/building-circuitpython\"\u003ehttps://learn.adafruit.com/building-circuitpython\u003c/a\u003e\nwhich walks you through all the necessary steps.\u003c/p\u003e\n\n\u003cp\u003eThere are a few problems though:\u003c/p\u003e\n\n\u003cul\u003e\n\u003cli\u003eyou will need to download and install a lot of software-packages. Some of\nthem might even need other versions than those that the packet-manager of your\ndistribution provides. Or they conflict with other projects you are working on.\u003c/li\u003e\n\u003cli\u003eIf you use a different flavor of Linux, you cannot just copy and paste the\ncommands from the guide but also have to change commands and package-names.\u003c/li\u003e\n\u003cli\u003eYour software-environment is bloated. Disks are very large these days, so\nthis is not the main problem, but backups take definitely longer (I assume\nthat you \u003cem\u003edo backup your computer\u003c/em\u003e).\u003c/li\u003e\n\u003c/ul\u003e\n\n\u003cp\u003eYou could use a dedicated development machine or a virtual machine, but setting\nthis up is again additional work.\u003c/p\u003e\n\n\u003cp\u003e\u003cem\u003eGithub Codespaces\u003c/em\u003e are a solution for all of these problems. A \u003cem\u003eCodespace\u003c/em\u003e is a\nsort of virtual Linux-system. Technology wise it is a Linux container running\nwithin docker in the cloud. If you have a Github account, you can create such\na system within seconds. You just head to \u003ca href=\"https://github.com/codespaces\"\u003ehttps://github.com/codespaces\u003c/a\u003e and\ncreate a codespace from one of the templates (the \"Blank\" template is just fine).\u003c/p\u003e\n\n\u003cp\u003eThe interface to the codespace is the web-version of \"Visual Studio Code\" (VSC), so\nyou have a state-of-the-art editor, terminals, git and so on - all from within\nyour browser. As an alternative, you can install VSC on your local machine, add\nthe codespace-extensions from the VSC-marketplace and connect from your local\nVSC to you codespace. This is higly recommended, since the browser\nversion is sometimes sluggish.\u003c/p\u003e\n\n\u003cp\u003eSince codespaces use ressources in the cloud, Github charges for using them.\nThe good news is that the free plan of every account has 120 CPU-hours and\n15GB storage per month included. The minimal machine has 2 CPUs, so this\nboils down to 60 hours per month. This should be enough unless you are a\nprofessional developer.\u003c/p\u003e\n\n\u003ch2\u003eAutomatic Setup for CircuitPython\u003c/h2\u003e\n\n\u003cp\u003eAt this point, you could just create an empty codespace from the template and\nfollow the guide from Dan. I actually recommend that you do that once, since\nyou will learn about the different tools you need to install.\u003c/p\u003e\n\n\u003cp\u003eFor regular use, it is much simpler to let Github do all this work. For this\nreason the CircuitPython repository has predefined codespace configurations\nfor most of the ports.\u003c/p\u003e\n\n\u003cp\u003eSo the normal workflow would look like this:\u003c/p\u003e\n\n\u003cul\u003e\n\u003cli\u003ecreate a fork of \u003ca href=\"https://github.com/adafruit/circuitpython\"\u003ehttps://github.com/adafruit/circuitpython\u003c/a\u003e\n\u003c/li\u003e\n\u003cli\u003ecreate a new development branch within your fork\u003c/li\u003e\n\u003cli\u003eclone this branch into a codespace\u003c/li\u003e\n\u003cli\u003ego for a coffee-break: the initial setup will take about 10 minutes\u003c/li\u003e\n\u003cli\u003eedit and build your own version of CircuitPython\u003c/li\u003e\n\u003cli\u003eadd, commit and push any changes back to your branch\u003c/li\u003e\n\u003cli\u003ecreate a pull-request for upstream\u003c/li\u003e\n\u003c/ul\u003e\n\n\u003cp\u003eYou can find detailed instructions for the third step in the Readme:\n\u003ca href=\"https://github.com/adafruit/circuitpython/blob/main/.devcontainer/Readme.md\"\u003ehttps://github.com/adafruit/circuitpython/blob/main/.devcontainer/Readme.md\u003c/a\u003e\u003c/p\u003e\n\n\u003ch2\u003eDaily Use\u003c/h2\u003e\n\n\u003cp\u003eOnce you have created your codespace, you can keep it and use it whenever\nyou want. Codespaces have two states: \"active\", i.e. running or \"stopped\".\nIn the latter state you are only charged for the storage, so don't forget\nto stop your codespace after you finished your work. Github will automatically\nstop your codespace after 30 minutes of inactivity. In your accout settings\nyou can change this value to something shorter. Also, Github will delete\nunused codespaces after 30 days of inactivity. But you will be prompted\nbefore this happens.\u003c/p\u003e\n\n\u003cp\u003eStorage size is a minor problem, since Github does not charge for the storage\nthat the standard Linux image uses. A fully operational codespace for the\nespressif-port e.g. has about 2.4GB, so the 15GB limit will be enough for\na number of codespaces.\u003c/p\u003e\n\n\u003ch2\u003eFurther Reading\u003c/h2\u003e\n\n\u003cp\u003eCodespaces are a powerful tool with many features not covered here. To\nfind out more, read the documentation: \u003ca href=\"https://docs.github.com/en/codespaces\"\u003ehttps://docs.github.com/en/codespaces\u003c/a\u003e.\u003c/p\u003e\n\n\u003ch2\u003eFinal Note\u003c/h2\u003e\n\n\u003cp\u003eThe scripts for the automatic setup of codespaces are not maintained by\nthe core CircuitPython developers. As CircuitPython evolves the buildsystem\nwill change and the scripts might stop working. In this case, it is best\nto create an issue.\u003c/p\u003e\n","metadata":{"markdown":"Using Github Codespaces for CircuitPython Development\n=====================================================\n\nIntroduction\n------------\n\nIf you wan't to contribute to CircuitPython, one of the hurdles you need to\ntake is the installation of the development environment.\n\nThere is a nice guide from Dan Halbert\n\u0026lt;https://learn.adafruit.com/building-circuitpython\u0026gt;\nwhich walks you through all the necessary steps.\n\nThere are a few problems though:\n  - you will need to download and install a lot of software-packages. Some of\n    them might even need other versions than those that the packet-manager of your\n    distribution provides. Or they conflict with other projects you are working on.\n  - If you use a different flavor of Linux, you cannot just copy and paste the\n    commands from the guide but also have to change commands and package-names.\n  - Your software-environment is bloated. Disks are very large these days, so\n    this is not the main problem, but backups take definitely longer (I assume\n    that you *do backup your computer*).\n\nYou could use a dedicated development machine or a virtual machine, but setting\nthis up is again additional work.\n\n*Github Codespaces* are a solution for all of these problems. A *Codespace* is a\nsort of virtual Linux-system. Technology wise it is a Linux container running\nwithin docker in the cloud. If you have a Github account, you can create such\na system within seconds. You just head to \u0026lt;https://github.com/codespaces\u0026gt; and\ncreate a codespace from one of the templates (the \"Blank\" template is just fine).\n\nThe interface to the codespace is the web-version of \"Visual Studio Code\" (VSC), so\nyou have a state-of-the-art editor, terminals, git and so on - all from within\nyour browser. As an alternative, you can install VSC on your local machine, add\nthe codespace-extensions from the VSC-marketplace and connect from your local\nVSC to you codespace. This is higly recommended, since the browser\nversion is sometimes sluggish.\n\nSince codespaces use ressources in the cloud, Github charges for using them.\nThe good news is that the free plan of every account has 120 CPU-hours and\n15GB storage per month included. The minimal machine has 2 CPUs, so this\nboils down to 60 hours per month. This should be enough unless you are a\nprofessional developer.\n\n\nAutomatic Setup for CircuitPython\n---------------------------------\n\nAt this point, you could just create an empty codespace from the template and\nfollow the guide from Dan. I actually recommend that you do that once, since\nyou will learn about the different tools you need to install.\n\nFor regular use, it is much simpler to let Github do all this work. For this\nreason the CircuitPython repository has predefined codespace configurations\nfor most of the ports.\n\nSo the normal workflow would look like this:\n  - create a fork of \u0026lt;https://github.com/adafruit/circuitpython\u0026gt;\n  - create a new development branch within your fork\n  - clone this branch into a codespace\n  - go for a coffee-break: the initial setup will take about 10 minutes\n  - edit and build your own version of CircuitPython\n  - add, commit and push any changes back to your branch\n  - create a pull-request for upstream\n\nYou can find detailed instructions for the third step in the Readme:\n\u0026lt;https://github.com/adafruit/circuitpython/blob/main/.devcontainer/Readme.md\u0026gt;\n\n\nDaily Use\n---------\n\nOnce you have created your codespace, you can keep it and use it whenever\nyou want. Codespaces have two states: \"active\", i.e. running or \"stopped\".\nIn the latter state you are only charged for the storage, so don't forget\nto stop your codespace after you finished your work. Github will automatically\nstop your codespace after 30 minutes of inactivity. In your accout settings\nyou can change this value to something shorter. Also, Github will delete\nunused codespaces after 30 days of inactivity. But you will be prompted\nbefore this happens.\n\nStorage size is a minor problem, since Github does not charge for the storage\nthat the standard Linux image uses. A fully operational codespace for the\nespressif-port e.g. has about 2.4GB, so the 15GB limit will be enough for\na number of codespaces.\n\n\nFurther Reading\n---------------\n\nCodespaces are a powerful tool with many features not covered here. To\nfind out more, read the documentation: \u0026lt;https://docs.github.com/en/codespaces\u0026gt;.\n\n\nFinal Note\n----------\n\nThe scripts for the automatic setup of codespaces are not maintained by\nthe core CircuitPython developers. As CircuitPython evolves the buildsystem\nwill change and the scripts might stop working. In this case, it is best\nto create an issue."}}]