How to Edit Rules
Before you start editing a rule, the first question to ask yourself is, why?
The rules exist to document solutions to recurring problems, if it's happened more than once, then it's probably worth making a rule.
Generally, every rule should document the reasons for adopting a specific solution, but not necessarily how to get there.
Editing on GitHub is sooo much better than sending an email in the format of change x to y. It's fast, allows us to look at previous changes and gives you credits on your GitHub stats!
Better again is using the newly added Netlify CMS interface to edit rules without the hassle of worrying about branches, forks and pull requests. All of this is done automatically behind the scenes, and you still get all the benefits to your stats!
Figure: Some good GitHub stats 😄
Using the Netlify CMS interface to edit rules is easy! Simply follow these steps:
- Navigate to the rule you want to edit on SSW Rules.
- Click the pencil icon to open the Netlify CMS editor.
Figure: Click to edit
- You might need to log in to netlifycms with your GitHub account at this point
Figure: Netlify Login with GitHub page
- Use the editor in the left column to edit the details of the rule (ideally in Markdown, rather than rich text, as this minimises unwanted artifacts from the CMS). You can preview your changes in the right column as you make them.
Note: The actual content of the rule is in the Body field.
Figure: Netlify CMS interface for a rule
- Tip: If you have substantially improved a rule, feel free to add yourself to the acknowledgements section.
See How-to-Add-an-Acknowledgment.
- Click 'Save' to save your changes to the rule as a draft.
Note: To delete these changes use the 'Delete unpublished changes' button next to 'Save'.
Figure: Changes saved as a draft.
- When you are ready to publish your changes, setting the status to 'In review' submits your changes for approval before they are added to SSW Rules.
Note: If you don't want to publish just yet, your changes will be waiting for you as a draft. Simply open the editor again when you're ready to continue editing.
Figure: Set the status to 'In review'
-
Navigate to SSW.Rules.Content | Pull Requests and open your pull request. Add a title and fill out the description fields. (As per Do you know how to write a good pull request?)
-
Check the status of your changes in the Workflow tab of Netlify CMS. You can see all changes that are drafted and in review.
Figure: See all your edited rules
We use forks to edit rules because they don't require write permissions to the SSW.Rules.Content repository, which many people don't have!
To get started, do you have a fork of the SSW.Rules.Content repository? If not, follow the steps in this wiki page: Creating your Fork (One time setup)
Now you have your forked repository, follow these steps:
- Go to your forked repository: {User}/SSW.Rules.Content.
- Navigate to a file you want to change. You can use the
Go to filebutton to search for a rule.
Note: Alternatively, use the 'Edit in GitHub' button on a rule or category in the SSW Rules website to open it in GitHub.
Figure: Search for your file by clicking Go to file
- Click on the pencil button to edit the file.
Figure: Click edit a rule
- Once you are happy with your changes, scroll to the bottom of the page to the commit box. Add a useful commit message and description, and make sure you are committing directly to the main branch of your forked repository.
Figure: Commit your changes
- Merge your changes, by following Merging Your Fork
If you haven't touched your Fork in a while, it might be quite far behind the SSW.Rules.Content repository. You can tell if it is behind by looking at the message on your fork, as shown below. Follow the steps here to update your fork: Updating your fork
Figure: Message indicating out of date fork.
All rules are written in Markdown, and so you're going to need to know it if you want to edit one! If you want to brush up on your skills, see Using Markdown.
Figure: A rule using markdown