====================== Contribution Standards ====================== Standards help to improve the quality of our product and its development. Herein we define our standards for processes and development to maintain consistency and function well as a community. It is a work in progress; modifications to this document should be discussed and agreed upon by the community. -------------------------------------------------------------------------------- Code ==== This provides an outline for standards we use in our codebase to keep our code easy to read and easy to maintain. Much of our code guidelines are based on the book `Clean Code <http://www.pearsonhighered.com/educator/product/Clean-Code-A-Handbook-of-Agile-Software-Craftsmanship/9780132350884.page>`_ by Robert Martin. We maintain a Tech Glossary to provide consistency in terms and symbolic names used for items and concepts within the application. This is found in the CE project in /docs-internal/glossary.rst Refactoring ----------- Make it better than you found it! Our codebase can always use improvement and often benefits from refactoring. New code should be refactored as it is being written, and old code should be treated with the same care as if it was new. Before doing any refactoring, ensure that there is test coverage on the affected code; this will help minimize issues. Python ------ For Python, we use `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_. We adjust lines of code to under 80 characters and use 4 spaces for indentation. JavaScript ---------- This currently remains undefined. Suggestions welcome! However, we have decided to go forward with W3C standards and picked WebComponents as the foundation of user interface. New functionality should be implemented as components using the `Polymer Project` <https://www.polymer-project.org>`_ library and should avoid external dependencies like `jquery`. HTML ---- Unfortunately, we currently have no strict HTML standards, but there are a few guidelines we do follow. Templates must work in all modern browsers. HTML should be clean and easy to read, and additionally should be free of inline CSS or JavaScript. It is recommended to use data attributes for JS actions where possible in order to separate it from styling and prevent unintentional changes. LESS/CSS -------- We use LESS for our CSS; see :doc:`frontend` for structure and formatting guidelines. Linters ------- Currently, we have a linter for pull requests which checks code against PEP8. We intend to add more in the future as we clarify standards. -------------------------------------------------------------------------------- Naming Conventions ================== These still need to be defined for naming everything from Python variables to HTML classes to files and folders. -------------------------------------------------------------------------------- Testing ======= Testing is a very important aspect of our process, especially as we are our own quality control team. While it is of course unrealistic to hit every potential combination, our goal is to cover every line of Python code with a test. The following is a brief introduction to our test suite. Our tests are primarily written using `py.test <http://pytest.org/>`_ Acceptance Tests ---------------- Also known as "ac tests", these test from the user and business perspective to check if the requirements of a feature are met. Scenarios are created at a feature's inception and help to define its value. py.test is used for ac tests; they are located in a repo separate from the other tests which follow. Each feature has a .feature file which contains a brief description and the scenarios to be tested. Functional Tests ---------------- These test specific functionality in the application which checks through the entire stack. Typically these are user actions or permissions which go through the web browser. They are located in rhodecode/tests. Unit Tests ---------- These test isolated, individual modules to ensure that they function correctly. They are located in rhodecode/tests. Integration Tests ----------------- These are used for testing performance of larger systems than the unit tests. They are located in rhodecode/tests. JavaScript Testing ------------------ Currently, we have not defined how to test our JavaScript code. -------------------------------------------------------------------------------- Pull Requests ============= Pull requests should generally contain only one thing: a single feature, one bug fix, etc.. The commit history should be concise and clean, and the pull request should contain the ticket number (also a good idea for the commits themselves) to provide context for the reviewer. See also: :doc:`checklist-pull-request` Reviewers --------- Each pull request must be approved by at least one member of the RhodeCode team. Assignments may be based on expertise or familiarity with a particular area of code, or simply availability. Switching up or adding extra community members for different pull requests helps to share knowledge as well as provide other perspectives. Responsibility -------------- The community is responsible for maintaining features and this must be taken into consideration. External contributions must be held to the same standards as internal contributions. Feature Switch -------------- Experimental and work-in-progress features can be hidden behind one of two switches: * A setting can be added to the Labs page in the Admin section which may allow customers to access and toggle additional features. * For work-in-progress or other features where customer access is not desired, use a custom setting in the .ini file as a trigger. -------------------------------------------------------------------------------- Tickets ======= Redmine tickets are a crucial part of our development process. Any code added or changed in our codebase should have a corresponding ticket to document it. With this in mind, it is important that tickets be as clear and concise as possible, including what the expected outcome is. See also: :doc:`checklist-tickets`