Content List

• Handling Incoming Webhooks
  • Building your Webhook Handler
  • Extracting information from the Request Body
• Example Webhook Handler with Slack
  • Setting up your SashiDo app
  • Cloud Code
  • Setting up Slack
  • Lets try it out!
• Other UseCases and Scenarios
• Useful Links

Introduction

Have you ever wanted to integrate a 3rd Party Client with your SashiDo applications? I suppose you have, and there's an awesome feature called WebHooks which help you do just that. In simple terms, a WebHook allows any 3rd Party Client, that supports Webhooks, communicate and send information (Payload) to your Parse Server instance and vice-versa.

If you want to get more familiar on how to send WebHooks from your SashiDo application to 3rd Party services, check our article on How to set up WebHooks on SashiDo or watch out YouTube Video Tutorial.

Sending your own WebHooks is one thing, but let's say you want to Handle a WebHook sent from a 3rd Party Client, do something with the information, and respond back. Such WebHooks are also called Incoming WebHooks and the only thing you need to set up is a simple WebHook Handler.

Handling Incoming WebHooks

Handling an Incoming WebHook is a really easy task! An Incoming WebHook is just an HTTP GET or POST request that sends some information to your Parse Server.

As you may already know, every time you create an application with SashiDo, we automatically give you a Free Private GitHub Repository for it. In order for you to process the WebHook from your Parse Server, all you need to do is implement a Express route handler within your app.js file. That’s called Advanced Cloud Code and we’ve made an article about it. You can check the Useful Links section for a direct link to the article.
The app.js file is located in your application's GitHub Repository, in the cloud folder.
So let's get straight to the point!

Building your WebHook Handler

Let's first navigate to the app.js file. Navigate to Dashboard -> your app -> Core -> Cloud Code and click on the blue button Manage on GitHub in the upper right corner.

When you're in your repository, open the Cloud folder and you'll find the file app.js.

Now it's time to write the Express route handler.

   app.post('/webhookHandler', function(request, response) {
    console.info('Received!'); // Log every time a WebHook is handled.

    // Execute any logic that you want when the 3rd Party Client hits that endpoint

    response.status(200); // Let the sender know that we've received the WebHook
    response.send();
});

Afterwards, you can access the handler by adding /webhookHandler to the end of your Server URL. The Server URL is just the API URL Address without the /1/. You can find it in Dashboard -> Your App -> App Settings -> Security & Keys. It should look something like this https://pg-app-sd5ez1yjgta5vksvux7wdfjwiykcpt.scalabl.cloud/webhookHandler

Yes, it's that simple!

Let's break this down a bit. First, we define the app.post route handler with an endpoint /webhookHandler. You can name the endpoint whatever you want, but for the sake of simplicity, we call it like that.

After that, we can simply put console.info(‘Received!’) so we can track when we've received WebHooks through our Logs section in the Dashboard.

ProTip: It's good practice to handle the WebHook quickly, as most services require you to respond in a few seconds, otherwise, you'll get a Timeout error. If you just need to execute some custom logic of yours after receiving a WebHook, without responding to it, a simple response.status(200) and response.send() would do just fine to tell the service that you’ve received the WebHook. If you need to respond to the Webhook then you should always check the Docs of the 3rd Party Service so you know in what time interval you need to respond and in what format. Some services may have a responseURL attached with the Payload. You can use it if you need to send information back to the 3rd Party Service after some time.

You may also find the Express Docs useful so check them out too if you’d like. You can also check the Express Request/Response references.

That's about it. Now you can execute any logic that you want when you receive the WebHook! All good, but let's say you want to extract the payload and do something according to it.

Extracting information from the Request Body

Extracting information from the request is pretty easy too. We can use the Express Body Parser for that.

Include it at the beginning of your app.js file like this:

const bodyParser = require('body-parser');

app.use(
    bodyParser.urlencoded({
        extended: true
    })
);

app.use(bodyParser.json()); // If you are processing a JSON formatted Content-Type

After you define the Body Parser you can use it to convert the information to something readable and then use it in some way.

Most 3rd Party Services provide you with unique Verification Token. When they send you a WebHook, they also include the Verification Token in the payload. That way, you can make sure that the WebHook is coming from the desired 3rd Party Client by comparing your Verification Token with the one sent with the WebHook payload like this:

app.post('/webhookHandler', function(request, response) {
    var payload = JSON.parse(request.body.payload);
    if (payload.verificationToken !== 'your_verification_token') {
        response.status(403).end('Access forbidden');
    }
    ...
});

You should note that every 3rd Party Client may send different information and with Content-Type, so always be sure to check what payload is sent through the WebHook so you know exactly how to process the information.

If you want to learn more about the body parser, check out the body-parser npm package. It’s already installed so you don’t have to do it.

Here’s how your app.js file would look like if you followed the steps:

/*
 * Advanced Cloud Code Example
 */
const express = require('express');
const app = express();
const bodyParser = require('body-parser');

app.use(
    bodyParser.urlencoded({
        extended: true
    })
);

app.post('/webhookHandler', function(request, response) {
    var payload = JSON.parse(request.body.payload);
    if (payload.verificationToken !== 'your_verification_token') {
        response.status(403).end('Access forbidden');
    } else {
        response.status(200);
        response.send();
    }
});

/*
 * Exporting of module.exports.app is required.
 * we mount it automatically to the Parse Server Deployment.
 */

module.exports = app;

Example WebHook Handler with Slack

It's time to put everything from above into a good example, in this case, with Slack.

As you may already know, Slack is one of the most used chat platforms by developers. But did you know that you can integrate it with your SashiDo application? For example, let us say that you want to have a Slash Command that will list all unbilled users of your application and another Slash Command which will try to bill them. Well, the good news is that this can be done pretty easily using Slack apps and WebHooks!

1. Setting up your SashiDo app

1. Navigate to Dashboard -> Your App -> Core -> Browser -> User Class.
2. Create a new column of type boolean and name it billed.
3. If you don't have any entries in the User class, add some users and set the billed field of some of them to false
   • Easiest and fastest way to add new entries in your User class is to go to Dashboard -> Your App -> Core -> API Console.
   • For Request Type choose POST, be sure to check the Use MasterKey toggle to be true.
   • Set the endpoint to classes/_User.
   • In Query Parameters type {"username":"someUsername","password":"somePassword","billed": false} and hit Send Query.

2. Cloud Code

For this example, we’ve implement 2 Slash Commands:

• /unbilled - Will retreive all unbilled users.
• /bill - Tries to bill all the unbilled users.

For each of the two, we’ve created a separate WebHook handler which we've included in a separate file. We've provided a direct link to it at the end of this section.

Now let’s see how the handler for the /bill command works. First, we define the route handler with an endpoint of /billUser.

app.post('/billUser', async (req, res) => {});

After that, we execute our custom logic to try and bill our users:

app.post('/billUser', async (req, res) => {
    // Find all unbilled users
    const unbilled = await new Parse.Query(Parse.User)
        .equalTo('billed', false)
        .find();

    // Iterate through all the user objects
    for (let user of unbilled) {
        await user.save({ billed: true }, { useMasterKey: true });
    }

    // When it's done, we send back a response to Slack
    res.send({ text: `${unbilled.length} users successfully billed!` });
});

For the sake of simplicity, we've modified the code so it's short and readable. If you want to check the full code, which includes error handling and the /unbilled Slash Command Handler, you can check the app.js file in our Demo app.js Example Code file. If you want you can even copy-paste the code in your app.js file.

3. Setting up Slack

1. Go to Slack and create your own Workspace.
2. After that, create a new Slack App. Name it whatever you want and select the Workspace in which you want to implement it.
3. Navigate to Slash Commands in the section Add features and functionality and click on Create New Command.
   • For Command, type /unbilled (this is the name of your Slash Command).
   • In Request URL type your ServerURL + the route we defined in the app.js file. You can find your SashiDo App's ServerURL in Dashboard -> Your App -> App Settings -> Security & Keys -> API URL Address. Just replace the /1/ at the end with /getUnbilledUsers. It shoud look something like this - "https://pg-app-sd5ez1yjgta5vksvux7wdfjwiykcpt.scalabl.cloud/getUnbilledUsers".
   • Add a short description to the command and optionally a hint, then click on Save.
   • Repeat for the /bill Slash Command. Just replace the Request URL endpoint to /billUser (that's our second route handler in the app.js file).

4. Let’s test it out!

So, we've implemented 2 Slash Commands - /unbilled, which will return all of our unbilled users, and /bill which will try to bill all unbilled users.

Let us try it out and see what happens!

First of all, we can see that we have a few unbilled users in the picture below:

Let's head to our Slack Workspace and try out our newly implemented Slash Commands.

We can even check our Logs section in Dashboard -> your app -> Core -> Logs to see if the process went well internally. In our case, everything was fine, as we can see in the picture below:

We've also implemented logic to handle scenarios should there be no unbilled users. If you execute any of the above Slash Commands in this case, you'll get the following response:

That's about it. As I said before, pretty simple, right?

Other use cases and scenarios

By now you've learned how to handle WebHooks. Let's look at some use cases.

Approving Comments/Uploads

Let's say that you have an application in which your users can comment and upload pictures. You would probably want to regulate which comments and pictures are uploaded in some way.

One neat example is an integration with Slack and your SashiDo application with WebHooks. It would work in a way that when a person uploads or makes a comment, a WebHook will be fired to Slack, notifying you and your team and letting you choose whether the comment or picture is appropriate or not. After you've made your choice, another WebHook will be fired, this time to your SashiDo App. After handling it with your custom logic, the picture/comment will be posted or not, and you can send a message to the person if the content is not appropriate.

If you want to read more about Slack's WebHooks, Interactive messages & Buttons check out the following links:

• Slack Incoming WebHooks
• Slack Interactive Messages
• Slack Buttons

Billing service

Say you want to have a paid plan for your SashiDo application. You can imagine how hard it would be to write your own custom billing service and so on. That can be easily avoided by integrating a 3rd Party Billing Service like Chargebee for example, with your SashiDo app using WebHooks.

If you're interested and want to learn more about it, check out Chargebee's Events & WebHooks

Chat/Ticketing

Have you ever want to get feedback from your users, handle problems and issues that they might have, but don't want to write such features from scratch? With WebHooks you can do just that. For example, you can use 3rd Party Chat/Ticketing Services like Intercom or Teamwork and integrate them with your SashiDo apps using WebHooks.

If you're interested in such integration, you can check out both Teamwork and Intercom's Documentation about WebHooks.

SMS & Calling

Depending on what your application's about, you can choose to have SMS & Calling through it. That, by itself, would be a very laborious task if you choose to code it yourself. With WebHooks, you can use a service like Twillio to send text messages and make calls from your application.

If you're interested in SMS & Calls integration for your application, you can check our blog post GitHub integration of Advanced Cloud Code part 1 or Twillio's Documentation

Useful Links

• If you want to learn how to run your Advanced Cloud Code locally check out our blog post GitHub integration of Advanced Cloud Code Part 2.
• You can also check our tutorial on How to set up Cloud Code on SashiDo.
• Watch our YouTube Video Tutorial on Simple Cloud Code on SashiDo

Final

Whoa! That was a lot to take in. The great part is that you can use this information to your advantage and integrate your SashiDo apps with some other cool services!

Happy coding!

If you have ever wanted to update the configuration of your app on the fly, you should know how frustrating it is that the little update would require a fresh app release. Fortunately, Parse Config is here to the help! It's a very simple, yet at the same time, incredibly useful feature which allows you to add parameters to your app, which you can update whenever you want, without worrying that configuration changes will require a new release. It is stored as a configuration object on your Parse Server instance, so you can fetch it at any given time. So let's get to the point.

Getting Started

It's fairly easy to start using Parse Config. In your SashiDo applications you can do that in Dashboard -> Your App -> Core -> Config. Afterwards, you have to create the new parameters, which you'll be able to use and update whenever you want.
To do that click on the green button Create your first parameter or the Create a parameter button in the top-right corner of the Dashboard.

Alright, so far so good. Now you'll need to specify a couple of things:

• Parameter Name - It can be anything, but we suggest that it's something informative in regards to what you'll use it for.

• Type & Value - Those two go hand-to-hand with each other. You may wonder what data type your parameters can be, but don't worry as Parse Config supports nearly any data type:

  • Boolean - This is the standard true/false data type. You can toggle if it's true or false with just one click! Red is false and green is true.
  • String - Any form of text for example "Hello from SashiDo's blog!"
  • Number - You can use this for both integer type numbers like 1; 2; 3; and for floating-point number e.g 2.6; 10.65; 1.05 etc.
  • Date - It's self-explanatory, a date format. You can even set whatever time you like to your date. When you choose this type a little calendar-like window appears when you click to set the value.
  • Object - Any object that contains key/value pairs.
  • Array - An array of items, for example, strings, numbers, objects or dates ["user1","user2","user3"]; [1,2,3,4]; [{“George”:true},{“Alexa”:false}]. As you can see they can be from any data type and even in JSON format.
  • Geo Point - With this you can specify coordinates to a location with given Latitude & Longitude.
  • File - Last but not least, your parameter could be a file. You simply need to upload it.

If you want to edit your parameter, just hit the Edit button. In case you feel that you don't have any more need of it, just delete it by clicking the Delete button.

Take into consideration that you can have up to 100 different parameters or a total size of 128KB across all parameters as described in the Official Parse Server JS SDK here.

That's it! Now you have created your parameter. All good, but now you may ask yourself, how do I fetch what I've created from my client?

Retrieving Config

Let's say we've created a parameter dailyMessage of type string with a certain value, like "Today's specialty is Pineapple Pizza!". Let's assume that for our example we are building our application with JavaScript. You can simply retrieve your parameter like this:

  Parse.Config.get().then(function(config) {
    var dailyMessage = config.get("dailyMessage");
    // Now display your message wherever you want!
}, function(error) {
    // Something went wrong (e.g. request timed out)
});

Note that Parse.Config.get(); by itself will fetch all your parameters from the server.

As you can see it's fairly simple! The cool part is that the JavaScript SDK, or any other as a matter of fact, automatically caches your last fetched Config, so you are not required to retrieve it again after the application has been restarted. How cool is that? Simply awesome! It's build to be as reliable as possible even if your internet connection is poor. You can always fetch your cached Config and assign it to a variable like in the example below:

   var config = Parse.Config.current(); // Note that this will return all cached parameters.
   config.get("dailyMessage"); // Here you specify exactly which parameter’s value you want.
   
   // Now you can do something with it.

A great addition is that every Parse Config instance that you get is immutable. That means that if in the future you retrieve a new Parse Config from the server, it will not change or modify any existing Parse Config instances. It will lazily create a new instance and make it available through Parse.Config.current(). As you may have already guessed that means that you can safely use any current() object that you've created without worrying that it will be automatically updated.

If you want to read more about how to retrieve Config with the SDK of your choice, check these links to the Official Parse Docs:

• How to Retrieving Config with the iOS SDK
• Retrieving Config with the Android SDK
• Retrieving Config the .NET + Xamarine SDK
• Retrieving Config with the MacOS SDK

ProTip

Save requests by retrieving Config only once in a while

As you may understand by now, it may be a little bit of trouble for you if you retrieve the Config every time you want to use it. If that's the case, you can always use the cached current object of your last fetched config. You can also implement a simple logic to retrieve the latest Config only once in while like this:

   const getConfig = function() {
    let lastFetch;
    const timeBeforeFetch = 1000 * 60 * 60 * 24; // Re-fetch the config from the server only if the given time has passed. In this example, one day.
    return function() {
        const currentDate = new Date();
        if (lastFetch === undefined ||
            currentDate.getTime() - lastFetch.getTime() > timeBeforeFetch) {
            lastFetch = currentDate;
            return Parse.Config.get();
        } else {
            return Promise.resolve(Parse.Config.current());
        }
    };
}();

That way you can save up on the requests you are going to make if you fetch the Config each time you need to use it. Rather try to fetch it again and if the required time hasn’t expired fall back to the cached Configs.

After that you can retrieve your desired parameter like that:

const config = await getConfig();
config.get(‘yourParameterName’);

Other UseCases and Scenarios

So far you've learned how to create your parameters and retrieve them. However, it may still be hard for you to think of a way to use Config.

Feature Beta Testing

A good example is if you want to add this cool new feature to your application. Yet you want some of your users to test it out, but not all of them. Okay, that's awesome, as you can use two parameters of the Config to accomplish it.

For starters you can add a parameter of type Array called "betaTestUsers". In it you can add all the User IDs you would like the feature to be available for beta testing. After that, you can create a second parameter of type Date. You can call it whatever you want, let's say "featureStart. That way you can specify exactly at what date and time the feature should be made available to the given users. Cool, isn't it? You can edit your betaTestUsers to include or exclude testers at runtime without worrying that you need to re-deploy your application.

Cooking app, Recipe of the Day

Let's gaze upon another example. Say you have an application for cooking all sorts of pizza. You can have all sorts of different recipes but you can have a little special section for Today's Special Recipe.

Cool idea, don't you think? But with it comes the part where you would like to update that special recipe and for an example a picture of how it would look like when done. You can imagine how frustrating it would be to re-deploy your app every day because of some little message and a picture, right? Well as Config supports both File and String parameter types you can achieve this quite easily without the need for a fresh release. Simply create a new parameter of type String and call it "dailySpecialRecipe" and add the description of your recipe there. After that, make another config of type File so you can upload whatever picture you like and change it whenever you wish.

It's always better with a video

Final

That's about it! You've learned of a way to update your applications' configuration on the fly. All that's left to do is let your imagination loose and take that information to your advantage!

Content List

• Introduction
• Milestones, Labels & Assignees
• Notifications, @mentions, and References
• Search
• Other Uses

Introduction

Each application you create on SashiDo has its own Free Private repository on GitHub.
As any great project, yours will probably need to have a way to track its bugs, tasks, and improvements. Great news, as GitHub has just the right feature for the job. Its called Issues and it’s GitHub’s way of tracking and dealing with these sort of things.

It’s really simple, as they function almost like an email, though the great part is that they can be shared and discussed with your team. Every repository comes with its own Issues section. So let's get straight to the point.

We can start by looking at Parse Server’s Issues section for example:

GitHub's tracker is also quite special. It offers excellent formatting and focuses on collaboration and references. You can check out how a typical issue on GitHub looks in the image below:

• You can see that there is a title and a description which informs us what the issue is about.
• There are some neat color-coded labels which help you filter and organize your issue by category.
• Milestones are very useful for linking issues with specific feature or project phase (e.g Weekly Sprint 9/5-9/16 or Shipping 1.0). They are like a container for issues.
• Every issue can have an assignee which is responsible for moving the issue forward.
• And of course comments let anyone with access to the repository provide feedback and suggestions.

Milestones, Labels & Assignees

At some point, you're going to have many issues and you may find it hard to find a specific one. Don't worry, because labels, Milestones & assignees are awesome features to help you filter and sort issues.

You can change and edit all of them by just clicking on their corresponding gears in the sidebar which is located on the right.

In case you do not see the edit button, that means that you do not have permission to edit the issue and you can ask the repository's owner to make you a collaborator, so you can get access.

Milestones

Milestones are a great feature to group up your issues, for example by project, a feature or even a time period. They can be used in many different ways in software development. Here are some examples:

• Beta Launch - You can include any bugs that need to be fixed before you release the beta. By doing so you make sure that you don't miss anything along the way.
• June Issues - If you have many things to get done, you can specify a Milestone with the given issues you would like to work on during a specific period of time.
• Redesign - A great way to handle issues regarding the design of your project as well as collecting new ideas along the way.

Labels

Labels are an exceptionally good way to organize your issues. There is no limit to how many labels you can have and you can even filter your issues by one or more labels at the same time.

Assignees

Each issue may have an assignee which is responsible for pushing it forward. That's a great way to assign a particular person to track the issue, and is familiar with it. That way he can easily track and push it forward.

Notifications, @mentions, and References

Communication is key to resolving any issue. By using GitHub's @mention system and references, you can link issues to the right people or teams so that the issues are resolved effectively. These features are really easy to learn and use and work in every text field as they're part of GitHub's text formatting syntax called GitHub Flavored Markdown.

If you want to learn more about the syntax, you can check GitHub's official guide on Mastering Markdown

Notifications

GitHub's way to keep you posted about your Issues is Notifications. They can be utilized so you are up-to-date with new issues or to simply know if someone's waiting for your input so they can continue with their work.

You can receive notifications by two ways - either by email or via the web. To configure these settings navigate to your notification settings.

If you plan to receive many notifications, it's suggested that you configure to receive Web & Email notifications for Participating and Web for Watching.

Given that you're using this configuration, you'll receive emails when someone specifically mentions you and you can visit the web-based interface to keep in touch with repositories you have interest in.

You can easily view your notifications in the Notifications Screen. It's located on the left of your avatar in the top-right corner of the page. There you can easily navigate through many notifications at the same time. You can mark them as read or you can mute a specific thread. You can speed up this process by using keyboard shortcuts. To check a list of available shortcuts press the ? on the page.

There is a little difference between muting a thread and marking it as read. When you've marked a certain thread as read, you will not be notified until there has been a new comment, whereas if you mute it, you will not receive notifications until you are specifically @mentioned in the thread. That gives you the power to choose which threads are important to you and which you are not interested in.

GitHub comes with an awesome feature which syncs your notification statuses. Basically, if you read a notification in your email, it will be marked as read in the web-based interface. Awesome, right. However, you should enable your email client to show images if you want this to work.

@mentions

In order to reference other GitHub users in Issues, we use the @mention system. We can do so in both the description and the comment section of an issue by including the @username of the person. When we mention someone like that they'll receive a notification about it.

If you want to include people to a given issue you can use the /cc syntax. Here's an example:

It looks like the images on our initial page are not loading.

/cc @alexSmith

That's great, but only if you know who exactly to include. In most cases, we tend to work in teams and that way we may not know who exactly could be of help. Don't worry, because @mentions work with teams within organizations on GitHub. When you @mention a team it will send notifications to everyone who's part of it. Let's say for example you create an organization named @MySashiDoApp and under it, a team @javascrip-devs. An example @mention, in this case, would look like this:

/cc @MySashiDoApp/javascript-devs

References

Quite often different issues are intertwined or maybe you just want to reference one into the other. This can be done by using the hashtag # followed by the issue number.

Hey @alexR, I think this issue may have something in common with #62

After you've done it, an event is created in issue #62 which looks something like this:

If you want to refer to an issue in an entirely different repo, just include the repository name like this alex/example_project#62

You can also reference issues directly in commits by including the issue number in the commit message.

If you preface the commit message with “Fixes”, “Fixed”, “Fix”, “Closes”, “Closed”, or “Close” and afterwards merge to master, the issue will automatically be closed.

All in all, references are great for adding visibility to the history of your project, as they profoundly link the work being done with the bug being tracked.

Search

You can find the search box at the top of the page.

You can apply different filters to your search, for example:

• Keyword - e.g. all issues mentioning the sidebar
• State - all issues mentioning the sidebar that are closed
• Assignee - all issues mentioning the sidebar that were assigned to @mdo

If you'd like to read more about the search, you can do so in the official GitHub Article about Using search to filter issues and pull requests

Other uses for Issues

Issues are not tied only for development purposes. In fact, they are quite useful to collaborate with your team on whatever issues you have. Here are some examples:

• Bug tracker for your house including such gems as the door being hung incorrectly
• Bug tracker for your open source projects
• Request for recipes, maybe you have a good gluten-free pizza dough recipe?
• MostlyAdequate's E-books
• The French Civil Code, as unlikely as it may sound.

Final

Whew! That was a long article, but you've learned how to manage and keep track of your issues.

Have you ever thought about how great it would be if you could customize your own workflow? Managing your project, schedule events, release checklists or manage some kind of specific feature work? Don't worry, because with GitHub's Project Boards you can do just that!
What’s awesome is that with every app you have on SashiDo, you get a Free Private GitHub repo, which includes the option to enable Project Boards by default.

Project Boards

There are generally two types of Project Boards:

• Repository Project Boards - These types of Project Boards are scoped only to pull requests, issues, and notes under a given repo.
• Organization-wide Project Boards - They may refer to pull requests and issues from any repository that is part of an organization.

Project Boards are great for managing and coordinating your workflow. They combine pull requests, issues, and notes, which are sorted in cards in columns of your choosing. You can easily drag and drop cards to re-arrange them, for example at the top of the column or in another column altogether. The same can be applied to the columns themselves. This is also made easier by using keyboard shortcuts, for which you can read more in the official GitHub Guide for Using keyboard shortcuts for Project Boards

Cards

The cards in a Project Board contain data relevant to issues and pull requests, for example, labels, assignees, status or who opened the issue or pull request. If you want to see more detail, you can click the link in the card. The cool part is that each card has a unique URL address, which means you can easily share and discuss a specific card with your team.

Notes

You can create a note in every column you desire. They generally function as a reminder or a reference to an issue or pull request from any repo on GitHub, but you can also simply add information related to the Project Board itself. If you want, you can create a reference card to another Project Board by adding a link to a note. However, there may come a time when simply a note is not enough for your needs. Should that time come, you can always convert it to an issue. If you want to read more about that, check out the official GitHub Guide on Adding notes to a Project Board.

Creating & Viewing Project Boards

Before anything else, it's important to know that only people with write access to a repository can create a Project Board. Likewise, anybody who has read access to the repo can view the board. In relation to organization-wide Project Boards, only members of the given organization can create/view Project Boards. Should an organization-wide Project Board contain any pull requests or issues from a repository you do not have view access to, the card will be redacted.

It's fairly simple to create a Project Board. First of all, you need to be in your repository main page. Once there, you can see a little tab called Projects located under your repo name. When you click on it, given that you do not have any Project Boards, you need to click on the green button named New Project.

To create an organization-wide Project Board, you need to navigate to Your profile. You can find it when you click on your avatar in the top-right corner of the page. When there, on the left side of the screen, click on your organization icon. After that, click on Projects -> Create a project.

In both cases, you'll be asked to fill in the Project Board name and provide a description. After you've filled the name and description, you can optionally choose a template for your new board. Templates help you quickly set up your Project Board. When you choose to create it with a given template, it will include already created columns and cards with tips on how to use the Project Board. There are 3 templates to choose from:

• Basic Kanban - Using this template you can track your tasks with To Do, In progress and Done columns.
• Automated Kanban - It's identical to the Kanban template, with a difference that the cards automatically move from To Do, In progress and Done columns. If you want to read more about automation, check out GitHub's Article "About automation for project boards."
• Bug Triage - If you want to emphasize your work on bugs this template is perfect for you. It prioritizes bugs with columns of To Do, High priority, Low priority and Closed.

The Activity view a really cool feature of the Project Board. It allows you to see the recent history, like if someone created new cards or moved them to another column. To access the Activity View, just click on the Menu.

Filtering enables you to easily find a specific card or some subset of cards in a Project Board by applying filters. For example, you can filter cards by author, assignee, label, state, type. If you want to read more, you can do so in GitHub's article Filtering Cards on a Project Board

There might come a time when you've completed all your task in the Project Board and don't need it anymore. You can always close it. You can do so by clicking on the Projects tab in your repo. When there you can choose which Project Board you want to close in the projects list.

Further reading about Project Boards

You've learned about Project Boards in general. However, it may still be hard for you to visualize how to use them or for what purposes so let us help you out a bit.

An example use of a Project Board is to categorize your issues & pull requests. For instance, if you plan on a new release of your application, you can create a Project Board that can hold all the issue, pull requests, bugs and notes that need to be cleared before your new release. You can categorize them by columns of your choosing like Next up, In progress, High priority, Low priority & Completed. That way it would be really easy for you and your team to get things done quickly and efficiently.

Don't forget that you can always draw inspiration from any open source projects on GitHub if you want. You can check Kubernetes' Projects section for example.

You can see that there is no limit as to how many Project Boards you can have, it can be one, it can be many. It solely depends on how you want to use them.

If you want to read in-depth about how to edit your Project Boards you can check GitHub's official article Editing a project board.

Perhaps you are more interested in learning how to easily add issues and pull requests to your Project Boards. In that case, you can read more about it in GitHub's Adding issues and pull requests to a project board.

A crucial step for a successful project is documentation. When you present documentation in your project, it's easier for people to get to know what your project's about. But don't forget to update it from time to time so it stays relevant and useful.

Fortunately, GitHub makes the process of creating and maintaining documentation very easy.

There are two basic ways you can publish your documentation on GitHub:

1. By using a README file - this is a simple way to inform others about your project.
2. Using Wikis - they are used to present in-depth information.

Creating your README

At SashiDo, we automatically create a FREE Private repository for each application you make. Even better, each repo comes with a README containing useful information about how and where to set up some features. That being said, you can edit the README in any way you like.

Alternatively if you want to create your own repository, at the creation page, GitHub asks you whether you want it to come with a set of files in it, and the README is a part of them. You can tick it so the README file will automatically be created when you create the repo.

If you haven't selected the option described above, GitHub makes it even easier for you by letting you know that you can create a README so others can get familiar with your work.

Formatting your README

There are many formats that you might choose for your README. The best approach is to have a general, informative format. That way people can easily understand what your project is about and start working on it.

A sample format would be something like this:

1. Project name - Who wouldn't include their project's name? GitHub even automatically adds your project name to the beginning of the README! It's also included in the README that's created with your SashiDo app's repo.
2. Description - What would a README be without a description? It should be clear and to the point, so it's easy for people to understand what your project is about.
3. Installation - Your project may be awesome and fun, but if you do not include a brief guide on how to install it locally it might irritate some people.
4. Usage - After you've told users how to install your project locally, you can include brief instructions on how to use it.
5. Contribution - If your project is a big one, you may consider adding guidelines on how people can contribute to it. You can check out GitHub's guide for setting guidelines for repository contributors.
6. Credits - It would be awesome if you emphasize and link to the project's creators and contributors.

If you want to have a longer, more in-depth documentation, Wikis are the way to go.

Creating a Wiki

Every repository on GitHub comes with a Wiki. To start using it, you only need to navigate to the Wiki tab in the toolbar and press the Create the first page button.

Adding Content

It's fairly easy to start editing the content of your Wiki. You just need to navigate to the Wiki, then press the Edit button.

The Wiki itself comes with an awesome editor. It's relatively easy and pleasant to use. It even lets you choose the type of format for your wiki, for example, GitHub Markdown, but you can use any format supported by GitHub Markup. This can be done in the drop menu in the editor. There's even a preview feature, which lets you see the formatted content. You can check it out by pressing on the Preview tab, right next to Write.

When you've added all the content you want, before you save it, you can add an Edit Message, notifying what and why you added/edited. GitHub automatically creates a transparent history of who and what people edited, added or deleted on each page. You can find information about the last person who committed to the given page right below the title. If you want a detailed history of the changes, you can click on that information and a page with the full history will be displayed.

Another awesome feature that the Wiki offers is that you can add a custom footer, in which you can store any contact details or license information regarding your project.

Adding Pages

Of course, one page will not be enough for an in-depth documentation. To add a new page to your Wiki, go to the upper-right corner and click on the New Page button.

Every page you create is automatically added to the sidebar in alphabetical order so you can navigate pages easily.

If that's not enough, you can even create your own custom sidebar. It's located right under the Pages list.

An important thing to know is that the Home page serves as the main page of your Wiki and should it be missing, some automatically generated content will be displayed at its place.

Syntax highlighting

Another awesome feature of the Wiki is that it supports syntax highlighting of code. If you want to check all the supported languages you can check them here.

To utilize the syntax, the code block must start with three backticks and you can specify the name of the language the block will contain, but it's optional. After you've inserted the code, the block must end with another three backticks at the same indent level as the first three.

Here's an example with JavaScript:

The following code block:

Renders to this syntax highlighted code sample:

You're ready to go!

You have adapted some vital information about how to best document and present your project on GitHub, regardless of whether your project is big in scope and requires a Wiki, or you're simply beginning and setting up a reasonable and compact README.

Few beautiful wikis and readmes examples

• https://github.com/krasimir/kuker/blob/master/README.md
• https://github.com/NYTimes/objective-c-style-guide
• https://github.com/parse-community/parse-server/wiki
• https://github.com/krasimir/react-in-patterns/blob/master/README.md
• https://github.com/guardian/frontend/wiki
• https://github.com/airbnb/react-with-styles/blob/master/README.md

Happy documenting :)

Intoduction

Whenever you are working on a project with your team there will probably be ideas about new features, an optimization, or all sorts of stuff regarding your project. You can imagine what a mess it would be if everyone starts to make changes to the code without consulting with their team leader, or even push the changes directly into production. The GitHub Workflow makes the whole process of managing your project a hell of a lot easier.

Whenever you create a new app on SashiDo, we automatically create a FREE Private repository for every app on SashiDo in GitHub, so any information in this article is applicable to it and you can give it a try.

The GitHub Workflow

You can divide the GitHub workflow in 4 basic steps:

1. Creating a Branch
2. Making a Commit
3. Opening a Pull Request
4. Review of the Pull Request/Merging

Creating a branch

Creating a branch helps you and your team test new ideas, add new features, applying a bug fix and so on, without making direct changes to the master branch. The newly created branch is a snapshot of the current branch you are in, but changes you make to it will not affect the master branch.

You can give the branch whatever name you want, but it's advisable to be descriptive, so your colleagues can know what's being worked on in the given branch. Here are some example branch names: refactor-authentication, user-content-cache-key, make-retina-avatars.

There’s only one rule you need to follow: anything in master is always stable and deployable.

It's important to note, that when you create a new branch, you're creating a copy of the branch you’ve selected. For example if you have two branches - master & development - if you're currently in the development one, and create a new branch, it will be a copy of the development branch and all the changes you’ve made to it.

Adding Commits

After you've created a branch you can start making changes to it. When you modify a file, you can commit the changes to the branch. Each commit has an associated message with it, explaining why a certain change was made. That way the commit creates a transparent history of what you did so others can follow up. Furthermore, each commit is considered a separate unit of change. That means that if at some point a bug occurs in the code or if you have a new idea on how to do things that’s better than your current one, you can always go back to where you started.

Opening a Pull Request

Pull Requests are a comparison of two branches. After you've made your commits you can open a Pull Request to start a discussion about the commits you made. Pull Requests are tightly integrated with the Git repository, so anyone can see exactly what changes would be merged if they accept your request.

Opening a Pull Request is fairly easy and it can be done at any given time. For example, you might have very small amount of code but you want to share the idea with your team so they can give you suggestions or directions. After you’re pretty much sure that you’ve done all you can, you can open a Pull Request so others can view the work you’ve done and decide whether it’s alright.

You can even notify specific people using the mention system. That way, a specific person can be pinged that you would like to review the request so no one stays out of the loop. You can do that with the following syntax - @name.

Pull Requests are useful for contributing to open source projects and for managing changes to shared repositories.
Pull Requests are also very useful for the Fork & Pull Model. For example, your friend is developing an awesome application on SashiDo and you want to contribute to it. When you make a fork of your friend’s repository, GitHub creates a copy of its repo in your account. After you’ve made the changes and think that they might be relevant for your friend, you can open a Pull Request to start a discussion about them. If your friend likes them, he can merge the changes.

You can also consider using a Shared Repository model. That’s basically when collaborators are granted push access to a single shared repo and different branches are created when changes need to be made. In this model, Pull Requests are an awesome way to start a conversation regarding the changes you would like to make to the project.

Reviewing Pull Request & Merging

After you've made a pull request, your team may have comments or disagreements so you might have to change something and make further commits to your branch. Working that way ensures that nothing gets to production before it's well tested and approved. After everything is fine and your team accepts the changes you want to make, they can be merged with the master branch.

Deploying on SashiDo

What we’ve done for you on our platform is that when you merge/push to the master branch, your changes automatically deploy to SashiDo. That saves a lot of time, but you must be cautious because any changes to master will be reflected in your app.

Don’t worry, because there’s an easy way manage your workflow on SashiDo. For that purpose you can have two applications - one for production and one for development. That way it will be much easier to collaborate with your team and define what access any given person has. For example, you can add the new members to the development application. By doing so, you ensure that anything that's not tested or approved stays out of production. When everything is ready and good to go, the person responsible for changes in production can apply the changes to the production application.

It's always cool with video

Here is the official short GitHub Getting Started video on YouTube :)

And our short video how to start using the CloudCode with GitHub in SashiDo :)

Useful Links

• Find the official short GitHub Getting Started series on YouTube

• Getting Started with Cloud Code on SashiDo

• Getting Started with Website Hosting on SashiDo

• Getting Started with Webhooks on SashiDo