CONTRIBUTING.md

Contributing

Thank you for your interest in improving the Super Rentals Tutorial! This repository contains the logic to generate the prose markdown for our tutorial, as well as the code for the tutorial app itself.

Please note that all of the content to generate markdown and code are located in individual chapter files in /src/markdown. Any modifications/additions should occur there.

When building this tutorial you may notice that you have a /dist/markdown generated locally. Please note that this directory is not committed, and contains the output of your locally-generated tutorial content. Please be mindful not to modify anything in the /dist directory as it is git ignored and any changes there will not impact what is generate! Instead, make your changes inside of the /src directory only.

Making changes to the tutorial prose

If you are modifying or adding new prose to the tutorial, please be sure to follow the formatting style guide below! Following these conventions will make it easier to review your contribution. 😊

Formatting style guide

• When naming chapters, be sure that they are prefixed with two digits before the chapter name to ensure that they are ordered correctly.
  • For example: 01-orientation.md.
• When referring to filenames, be sure to specify the full relative path to a file. This is to make it easy to copy-paste the filename when people use the tutorial.
  • For example: "Let's start by creating a new file at app/components/jumbo.hbs."
• When referring to other chapters, link to the chapter using its relative path in the tutorial. Please be sure to include the trailing slash in the path so that the markdown will be linted correctly in the guides repo.
  • For example: We learned about this in a [previous chapter](../02-building-pages/).
• When referring to important key terms, be sure to italicize the term and link to a definition for it. This highlighting only needs to be done once, ideally on the first instance of the term. Note that, when using the "TODO" format (a placeholder for a link to be added in the future), we used [] rather than () to wrap the link markdown. This ensures that the generated output does not have broken links.
  • For example: *[route][TODO: add a link to route]*.
• When referring to component names, keywords, helpers, or HTML elements, be sure to use code markup.
  • For example: "Inside of this file, we have the <NavBar> component and the {{outlet}} keyword."
• When using the "Zoey says" callouts, be sure to use the blockquote formatting, ensuring that an extra > is included between the "Zoey says..." text and the actual note content. This is required in order to properly convert the markdown into HTML.
  • For example:

    > Zoey says...
    >
    > Here's a very helpful comment!
    

Making changes to the tutorial code

The workflow for updating the Super Rentals Tutorial involves working within two directories of this project: /src/markdown and /dist. The editable prose lives in src/markdown; any changes that are made to the prose should be done there. The tutorial uses the content in /src/markdown to generate the prose markdown that is output into /dist/markdown. Interspersed with the prose are commands that are used to generate the code for the actual tutorial app, which is outputted at /dist/code/super-rentals.

Once you have made your changes in the tutorial prose or code, you can run a few different commands to verify that your changes render as expected.

• To regenerate all of the chapters (and rebuild the app), run yarn build. This will rm -rf anything previously generated in the /dist directory.
• To generate a single chapter without removing all the previously generated content, run yarn generate src/markdown/07-your-chapter-to-edit-here.md. This will rebuild just the chapter that is specified without deleting everything else in the /dist directory. Please note that, before running this command, the current state of the /dist/code directory has to match the precise state of what it would be after running the generate command on the previous chapter. In other words, in order for the generate command to work correctly, the state of the code in /dist/code should match exactly the code that would be generated by yarn generate src/markdown/06-the-previous-chapter.md before it is run for src/markdown/07-your-chapter-to-edit-here.md .

Code changes

To make code changes, you will first need to locate the chapter you wish to edit in /src/markdown. Depending on the type of code change you'd like to make, you will need to use different commands.

Running commands

If you'd like to run a command, you will need to use the run: command. Be sure to include cwd=super-rentals so that the file is generated in the app's directory.

For example:

```run:command hidden=true cwd=super-rentals
ember generate component rental
```

Note that running a command by default will include the output of that command in the final markdown. To avoid output in markdown, you can use hidden=true or captureOutput=false as appropriate, as detailed in the README.

Creating files

To create a file, you will need to use the run:file:create command. Be sure to specify the language, the filename, as well as the cwd directory.

For example:

```run:file:create lang=handlebars cwd=super-rentals filename=app/templates/about.hbs
<h2>About Super Rentals</h2>
```

After creating a file, you should be sure to add it shortly afterwards so that it is tracked by git, and will be committed in the process of generating the tutorial app. This can be a hidden command, since it is not part of the prose of the tutorial.

For example:

```run:command hidden=true cwd=super-rentals
git add app/templates/about.hbs
```

If you are adding a test file, be sure to run ember test --path dist before adding the test file. This way, the generator will run the tests before adding them, and will fail in generating broken code if the tests themselves fail. The --path flag will speed up the test build and prevent test timeouts.

Using run:pause

When running commands, generating new files, or making changes to preexisting ones, you may want to see the current state of the generated app. The run: pause command is useful in this case. Use this command inside of your existing chapter, inserting it at points where you want the generator to stop. This is similar to running something like pauseTest(); it will pause the generator and allow you to see the current state of the code you have generated (located in /dist/code/super-rentals).

For example:

```run:pause
Note to self: check that `application.hbs` has the correct markup and remember to git add it!
```

Any content inside of the code blocks will be printed in your command line.

Generating diffs

⚠️ Please note: you may find it easier to generate diffs and make edits to the tutorial by opening /dist/code/super-rentals/code in a separate code editor window.

Before you start make any changes to capture a diff, navigate to /dist/code/super-rentals/code in the terminal. Run git diff and make sure there are no changes and that you have an empty diff.

In the case of generating diffs to render inside of the tutorial prose, you will want to use the run: pause command, described in the section above. Once you have put a run: pause at the spot in your prose where the diff needs to be captured, you can navigate to the /dist/code/super-rentals/code directory in your editor. In the app code, make whatever changes you need to make in whatever files need to be modified.

After you have made your code changes, navigate back to /dist/code/super-rentals/code in the terminal. First, check that the diff is included in the current changes:

➜  code git:(your-branch-name) ✗ git diff

Next, save your diff to some temporary file that you will open in a code editor in a moment (my_awesome_patch in the example below). You want to be sure to generate the diff specifically with only 1 line of context. You can do this by specifying git diff --unified=1 or git diff -U1.

➜  code git:(your-branch-name) ✗ git diff -U1 > my_awesome_patch
➜  code git:(your-branch-name) ✗ code my_awesome_patch

Once you have opened your temporary file containing your diff, edit it so that the only thing surrounding the diff is the line number additions subtractions.

```
@@ -9,2 +9,3 @@
Router.map(function() {
+  this.route('about');
});
```

Finally, wrap the newly-modified diff content in the run:file:patch command. Be sure to specify the language of the file, the filename, and the cwd=super-rentals option so that the patch is applied in the app's directory.

For example:

```run:file:patch lang=js cwd=super-rentals filename=app/router.js
@@ -9,2 +9,3 @@
Router.map(function() {
+  this.route('about');
});
```

Once you have added the diff to the prose using the run:file:patch command, you can remove the run:pause command. In order to test that your patch was successfully applied, be sure to:

1. Run git checkout any changes in the working directory of /dist/code/super-rentals/code.
2. Regenerate your modified chapter (yarn generate src/markdown/00-your-chapter-to-edit-here.md).

Finally, you can look at your modified chapter in /dist/markdown and make sure that your patch renders as you expect in the markdown!

Adding screenshots

TODO: add content!

Adding GIFs

TODO: add content!

Saving a chapter

Once a chapter is ready to be published and files, diffs, and screenshots have all been added as necessary, the last step is to commit the code changes at the end of the chapter. This is done using the run:checkpoint command.

For example:

```run:checkpoint cwd=super-rentals
Chapter 3
```

This should always be the last thing at the end of every chapter, as it will lint and run tests against the code generated in the chapter. The commit message will be whatever content is in the code block. We prefer the chapter title as the content of the commit.

Before opening a pull request, be sure to check the /dist/markdown to make sure that the markdown generated by your changes to a chapter still looks correct. Also lint the markdown by running the lint:md script.

Linting

Linting checks the markdown for spelling mistakes, repeated words, and markdown consistency. The linter also enforces brand and product name consistency. i.e Ember not ember or GitHub, not Github.

The super-rentals-tutorial uses the same linting rules as the guides. If linting passes here it will pass when merged with the guides. Most of the linting errors, except some spelling errors, will be self-explanatory.

Spelling Errors

The spelling dictionary used by the markdown linter contains many words common to the Ember ecosystem and general technology. It won't contain every possible word that could be used in the tutorial. Some real words or acronyms will be flagged as misspelled words.

Correctly spelled words flagged as misspelt can be added to the local dictionary file .local.dic. This will eliminate the spelling errors. Words added to the local dictionary should be in alphabetical order and all word cases added as necessary. i.e. both params and Params would need to be added if there both used in the tutorial.

Finally, the tutorial will be linted using the guides markdown linter when the PR is created. Since the linter will use the guides dictionary the words in .local.dic must also be in the guides .local.dic file for linting to pass.

When new words are added to the local dictionary, a separate PR must be opened on the guides to add them to the guides dictionary. If there are words that you think belong to the Ember dictionary, please open a PR in that repo.

Pull Request Merging

After the pull request is merged to the main branch, the generated markdown and code output will be pushed to a branch on the markdown/code output will be pushed to a branch on the guides and super rentals repos so that they can be further reviewed by their maintainers before integrating into the tutorial code/app and markdown.