Style Guide Now that you know what courseware as code is, how to register for an account, and have a general idea of how to contribute in a meaninful manner, its time to discuss the style with which you need to write your content so that we can quickly accept it. You will probably notice that we don’t follow our own style guide everywhere at the moment. Don’t interpret that as license to ignore it. Our processes took awhile to catch up to our content development and we are in the process of going back and cleaning up the battlefield to bring everything in line with this style guide. File Extensions and File Types All contributed material that isn’t source code, supporting assets (images, etc.), or explicitly required by a build system (e.g. .gitlab-ci.yml) must be in asciidoc format and end with the .adoc file extension. This requirement covers documents, slide decks, and more. Word documents, powerpoint slides, excel spreadsheets, and PDFs should never be present in the system, unless they’re a product of a pipeline. Workflow As previously mentioned, we use the github flow as the workflow across all Cyber School courses. The only branch that is offical (and deployable) is master. All other branches should be considered developmental, not suitable for usage, and unofficial. When one desires to make a change to the master branch, one should create a new branch, make the necessary changes, and do a merge request, all in rapid succession. Prior to doing a merge request, one should be sure that they have rebased their proposed branch against master. Branches that are behind master make it difficult to review and approve changes, and will be rejected. Each feature/bugfix that someone wishes to implement should be its own branch. Branches should never be long running, and should be deleted as soon as they are either merged in to master or rejected by the maintainers. When there is a particular point in the development history of the master branch that is of note (e.g. the exact commit that a course iteration starts on), tags are to be used to keep track of it for future reference. Using tags allows us to keep track of changes over time and correlate various changesets to differences in student outcomes, among other things. Sentences When writing in asciidoc, you must adhere to the one sentence per line style. Because asciidoc does not interpret single line breaks as actual line breaks, you can do things like this: The quick brown fox jumped over the lazy dog and have it render like this: The quick brown fox jumped over the lazy dog. I personally prefer to do one clause per line, so if there is a comma or a semicolon in a sentence, that would also trigger a line break. That level of detail is not required for general contributions, although certain projects may require it. Attributes and Metadata Attributes and metadata are an extremely important part of managing templatization-friendly repositories. The Cyber School uses them to keep track of various things, such as the various objectives covered in a particular lesson, the objectives that a quiz question is testing, etc. Each project will have their own metadata and attribute requirements. Be sure to adhere to them. You can read more about metadata and attributes here Pipelines While there is currently a shell-based gitlab runner that is available and used as default for all projects, this runner is deprecated and will be removed in the future. It has been replaced by a docker runner, which can be specified by using the 'docker' tag in your jobs. All new jobs should use docker, and all legacy jobs should be converted as soon as is practicable.