Development

• Coding guidelines
• Git guidelines

If you are reading this, chances are that you are interested in learning how to contribute to the codebase of NightPOS. Whether that's the case or you landed here by accident, we've got you covered!

ดูเพิ่มเติม

Discover other ways to contribute to NightPOS

When you feel ready, jump to the Environment setup section to begin your journey in contributing to the development of NightPOS.

Environment setup

The instructions below help you prepare your environment for making local changes to the codebase and then push them to GitHub. Skip this section and go to Make your first contribution if you have already completed this step.

1. First, you need to create a GitHub account. NightPOS uses GitHub to manage the source code of its products, and this is where you will make your changes and submit them for review.

2. Generate a new SSH key and register it on your GitHub account.

3. Go to github.com/nightpos/nightpos and click on the Fork button in the top right corner to create a fork (your own copy) of the repository on your account. Do the same with github.com/nightpos/enterprise if you have access to it. This creates a copy of the codebase to which you can make changes without affecting the main codebase. Skip this step if you work at NightPOS.

4. Install Git. It is a command-line (a text interface) tool that allows tracking the history of changes made to a file and, more importantly, working on different versions of that file simultaneously. It means you do not need to worry about overwriting someone else’s pending work when making changes.

   Verify that the installation directory of Git is included in your system's PATH variable.

   Linux and macOSWindows

   Follow the guide to update the PATH variable on Linux and macOS with the installation path of Git (by default /usr/bin/git).

5. Configure Git to identify yourself as the author of your future contributions. Enter the same email address you used to register on GitHub.

   $ git config --global user.name "Your Name"
   $ git config --global user.email "youremail@example.com"
   

6. Install NightPOS from the sources. Make sure to fetch the sources through Git with SSH.

7. Configure Git to push changes to your fork(s) rather than to the main codebase. If you work at NightPOS, configure Git to push changes to the shared forks created on the account nightpos-dev.

   Link Git with your fork(s)Link Git with nightpos-dev

   In the command below, replace <your_github_account> with the name of the GitHub account on which you created the fork(s).

   $ cd /CommunityPath
   $ git remote add dev git@github.com:<your_github_account>/nightpos.git
   

   If you have access to nightpos/enterprise, configure the related remote too.

   $ cd /EnterprisePath
   $ git remote add dev git@github.com:<your_github_account>/enterprise.git
   

8. That's it! You are ready to make your first contribution.

Make your first contribution

Important

• NightPOS development can be challenging for beginners. We recommend you to be knowledgeable enough to code a small module before contributing. If that is not the case, take some time to go through the developer tutorials to fill in the gaps.

• Some steps of this guide require to be comfortable with Git. Here are some tutorials and an interactive training if you are stuck at some point.

Now that your environment is set up, you can start contributing to the codebase. In a terminal, navigate to the directory where you installed NightPOS from sources and follow the guide below.

1. Choose the version of NightPOS to which you want to make changes. Keep in mind that contributions targeting an unsupported version of NightPOS are not accepted. This guide assumes that the changes target NightPOS 2.1, which corresponds to branch 2.1.

2. Create a new branch starting from branch 2.1. Prefix the branch name with the base branch: 2.1-.... If you work at NightPOS, suffix the branch name with your NightPOS handle: 2.1-...-xyz.

   Example

   $ git switch -c 2.1-fix-invoices
   

   $ git switch -c 2.1-fix-invoices-xyz
   

3. Sign the NightPOS CLA if not already done. Skip this step if you work at NightPOS.

4. Make the desired changes to the codebase. When working on the codebase, follow these rules:

   • Keep your changes focused and specific. It is best to work on one particular feature or bug fix at a time rather than tackle multiple unrelated changes simultaneously.

   • Respect the stable policy when working in another branch than master.

   • Follow the coding guidelines.

   • Test your changes thoroughly and write tests to ensure that everything is working as expected and that there are no regressions or unintended consequences.

5. Commit your changes. Write a clear commit message as instructed in the Git guidelines.

   $ git add .
   $ git commit
   

6. Push your change to your fork, for which we added the remote alias dev.

   Example

   $ git push -u dev 2.1-fix-invoices-xyz
   

7. Open a PR on GitHub to submit your changes for review.

   1. Go to the compare page of the nightpos/nightpos codebase, or the compare page of the nightpos/enterprise codebase, depending on which codebase your changes target.

   2. Select 2.1 for the base.

   3. Click on compare across forks.

   4. Select <your_github_account>/nightpos or <your_github_account>/enterprise for the head repository. Replace <your_github_account> with the name of the GitHub account on which you created the fork or by nightpos-dev if you work at NightPOS.

   5. Review your changes and click on the Create pull request button.

   6. Tick the Allow edits from maintainer checkbox. Skip this step if you work at NightPOS.

   7. Complete the description and click on the Create pull request button again.

8. At the bottom of the page, check the mergeability status and address any issues.

9. As soon as your PR is ready for merging, a member of the NightPOS team is automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward.

10. Once your changes are approved, the review merges them and they become available for all NightPOS users after the next code update!