Welcome to the Computer Science Field Guide (CSFG) developer community! We have spent many years creating the CSFG, and we would love for you to get involved into making this guide as great as possible! The following is a set of guidelines for contributing to the CSFG hosted on GitHub. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.
What should I know before I get started?
I want to contribute! Where do I start?
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected]
The Computer Science Field Guide (CSFG) is an online interactive resource for students learning about computer science. The project contains several components:
- Text for chapters, curriculum guides, and other pages.
- Images used within the guide.
- Interactive learning examples/demostations/games.
- Files for downloading (for example: PDFs, spreadsheets, code examples).
These are then put through our generator which reads a series of settings files and creates HTML output, currently in a website format.
There are many possible areas you can contribute, including:
- Suggesting a text edit for a typo, grammar correction, or just clearing up a point.
- Adding a new or replacement image for a chapter.
- Adding or modifying an interactive for the guide.
- Adding a translation for a chapter or interactive.
- Modifying the HTML generator.
Have a look at the following sections on how to contribute, and feel free to ask any questions on the public chatroom for the CSFG on Gitter.
This section guides you through submitting an issue for the CSFG. Following these guidelines helps maintainers and the community understand your findings.
Before creating an issue, please check this list as you might find out that you don't need to create one. When you are creating an issue, please include as many details as possible.
- Search the issue tracker to see if the issue has already been reported. If it has, add a comment to the existing issue (even if the issue is closed) instead of opening a new one.
Issues are tracked in the GitHub issue tracker (if you've never used GitHub issues before, read this 10 minute guide to become a master). When creating an issue, provide the following information.
Explain the problem and include additional details to help maintainers understand or reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Clearly and concisely describe the issue and provide screenshots if required.
- Link any related existing issues.
- Apply relevant labels for easier management by project maintainer.
If the issues is a code related issue, also include the following:
- Describe the exact steps which reproduce the problem in as many details as possible. For example, how you were using an interactive. When listing steps, don't just say what you did, but explain how you did it. For example, if you moved the cursor to the end of a line, explain if you used the mouse or a keyboard shortcut.
- Explain which behavior you expected to see instead and why.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
- Include screenshots and animated GIFs if it helps explain the issue you encountered.
- What's the name and version of the OS you're using?
- What's the name and version of the browser you're using?
- If the problem is related to performance, please provide specifications of your computer
This section guides you through submitting an enhancement suggestion for the CSFG, including completely new chapters of text to minor improvements of existing interactives. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an suggestion, please include as many details as possible.
- Search suggestions in the issue tracker to see if the suggestion has already been suggested. If it has, add a comment to the existing suggestion (even if the suggestion is closed) instead of opening a new one.
Issues are tracked in the GitHub issue tracker (if you've never used GitHub issues before, read this 10 minute guide to become a master). When creating an issue, provide the following information.
Explain the problem and include additional details to help maintainers understand or reproduce the problem:
- Use a clear and descriptive title for the issue to identify the suggestion.
- Clearly and concisely describe the suggestion and provide screenshots if required.
- Explain why this suggestion would be useful to most CSFG users and isn't something that should be a implemented as a community variant of the CSFG.
- Link any related existing suggestions.
- Apply relevant labels for easier management by project maintainer.
Unsure where to begin contributing to CSFG? You can start by looking through these beginner and help-wanted issues:
- Beginner issues - issues which should only require a few lines of text or code.
- Help wanted issues - issues which should be a bit more involved than
beginnerissues.
- Include a detailed explaination of the proposed change, including screenshots and animated GIFs in your pull request whenever possible.
- Read and applied the style guides listed below.
- Your pull request should be on a new branch from our
developbranch (unless it's something tiny like a typo). The naming conventions of branches should be descriptive of the new addition/modification. Ideally they would specify their namespace as well, for example:interactive/deceiverguide_content/data_representationissue/234
- Linked any relevant existing issues/suggestions.
- Applied the relevant labels for this pull request.
- Run the generation script and checked the output is as expected (be sure to run with various optional parameters, for example, teacher output).
- Added necessary documentation (if appropriate).
- Commits should be as descriptive as possible. Other developers (and even future you) will thank you for your forethought and verbosity for well documented commits. Ideally follow this commit structure, otherwise in short:
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally
- Use Vincent Driessen's Git Branching Model for managing development. Please read this document to understand our branching methods.
- Folders should be all lowercase with dashes for spaces.
- Folders and files should use full words when named, however the JavaScript, CSS, and image folders within interactive folders can be named
js,css, andimgrespectively.
Every line of code should appear to be written by a single person, no matter the number of contributors.
These are our abridged guidelines for working on code within this repository:
- Code should be easily readable (avoid abbreviations etc)
- Files should be set to
utf-8, uselfline endings, and have a final newline at the end of a file. - A file should begin with a comment listing main author, and purpose.
- Functions should have comments/docstrings explaining their purpose.
- Indents should be spaces (not tab characters)
- Indent sizes:
- HTML: 2 spaces
- CSS/SCSS: 2 spaces
- JavaScript: 4 spaces
- Python: 4 spaces
For more detailed specifications (including naming conventions, declaration order), we aim to follow these guides:
Our project deals with a large variety of materials with various licenses, some of which are used multiple times throughout the project. Instead of managing multiple license files, we have opted to storing all license information in one file (which is sent through our parser and displayed in the HTML output).
- Files used should be listed in
text/en/further-information/included-files.md. - Details on how to add license information is found at the top of this file.
We use a variety of software for developing the CSFG, but here are some of our favourites that you may find useful:
- We use a public Gitter chatroom for chatting to contributors.
- Most of us use Google Chrome's developers tools for testing and debugging our interactives and website design.
- And lastly, we use Git and GitHub for managing version control.
Internally we also use:
- A private Slack for planning and discussing topics as a team.
- Many different file editors including Atom, Sublime Text, vim, Notepad++, Brackets, etc (obviously vim is superior 👑).
This is our current process for creating and publishing a CSFG release.
- Create a release branch. Checkout to this branch.
- Update the version number within the
generator-settings.conf. Details on the numbering system is stored within the releases page. - Check logs for errors, how content is displayed (especially conditional content), and command line parameters. Fix any issues that arise, or log an issue.
- Detail the changes on the
further-information/releases.mdpage. This includes moving older versions to their new folders (if required) and creating links to their backups. New contributors should also be added tofurther-information/contributors.md. - Complete the release branch. Be sure to tag the release with the version number for creating the release on GitHub.
- Create the release on GitHub on the tagged commit.
- Upload a new version of the CSFG to our webserver.
- Announce release on CSFG teachers group.