docs: more comprehensive contributor docs #4039

docs/contributing/checklist-tickets.rst

@@ -0,0 +1,137 @@
+.. _checklist-tickets:
+
+=================
+Ticket Checklists
+=================
+
+
+Ticket Description
+==================
+
+In general these things really matter in the description:
+
+- Reasoning / Rationale. Explain "WHY" it makes sense and is important.
+
+- How to reproduce. Easy to follow steps, that’s important.
+
+  - Observation: The problem (short)
+
+  - Expectation: How it should be (short)
+
+- Specs: It is fine to draft them as good as it works.
+
+  If anything is unclear, please ask for a review or help on this via the
+  Community Portal or Slack channel.
+
+
+Checklists for Tickets
+======================
+
+BUG
+---
+
+Definition: An existing function that does not work as expected for the user.
+
+- Problem description
+- Steps needed to recreate (gherkin)
+- Link to the screen in question and/or description of how to find it via 
+  navigation
+- Explanation of what the expected outcome is
+- Any hints into the source of the problem
+- Information about platform/browser/db/etc. where applicable
+- Examples of other similar cases which have different behaviour
+
+DESIGN
+------
+
+Definition: Styling and user interface issues, including cosmetic improvements
+or appearance and behaviour of frontend functionality.
+
+- Screenshot/animation of existing page/behaviour
+- Sketches or wireframes if available
+- Link to the screen in question and/or description of how to find it via 
+  navigation
+- Problem description
+- Explanation of what the expected outcome is
+- Since this may be examined by a designer; it should be written in a way that a
+  non-developer can understand
+
+EPIC
+----
+
+Definition: A collection of tickets which together complete a larger overall
+project.
+
+- Benefit explanation
+- Clear objective - when is this complete?
+- Explanations of exceptions/corner cases
+- Documentation subtask
+- Comprehensive wireframes and/or design subtasks
+- Links to subtasks
+
+FEATURE
+-------
+
+Definition: A new function in the software which previously did not exist.
+
+- Benefit explanation
+- Clear objective
+- Explanations of exceptions/corner cases
+- Documentation subtask
+- Comprehensive wireframes and/or design subtasks
+
+SUPPORT
+-------
+
+Definition: An issue related to a customer report.
+
+- Link to support ticket, if available
+- Problem description
+- Steps needed to recreate (gherkin)
+- Link to the screen in question and/or description of how to find it via 
+  navigation
+- Explanation of what the expected outcome is
+- Any hints into the source of the problem
+- Information about platform/browser/db/etc. where applicable
+- Examples of other similar cases which have different behaviour
+
+TASK
+----
+
+Definition: An improvement or step towards implementing a feature or fixing
+a bug. Includes refactoring and other tech debt.
+
+- Clear objective
+- Benefit explanation
+- Links to parent/related tickets
+
+
+All details below.
+
+
+External links:
+
+- Avoid linking to external images; they disappear over time. Please attach any
+  relevant images to the ticket itself.
+
+- External links in general: They also disappear over time, consider copying the
+  relevant bit of information into a comment or write a paragraph to sum up the
+  general idea.
+
+
+Hints
+=====
+
+Change Description
+------------------
+
+It can be tricky to figure out how to change the description of a ticket. There
+is a very small pencil which has to be clicked once you see the edit form of a
+ticket.
+
+
+.. figure:: images/redmine-description.png
+   :alt: Example of pencil to change the ticket description
+
+   Shows an example of the pencil which lets you change the description.
+

docs/contributing/contributing.rst

@@ -12,6 +12,7 @@ Welcome to the contribution guides and development docs of RhodeCode.
 .. toctree::
    :maxdepth: 1
 
+   overview
    testing/index
    dev-setup
    db-schema

docs/contributing/dev-setup.rst

@@ -1,3 +1,4 @@
+.. _dev-setup:
 
 ===================
  Development setup

docs/contributing/frontend.rst

@@ -0,0 +1,152 @@
+
+==================================================
+ Code style and structure guide for frontend work
+==================================================
+
+About: Outline of frontend development practices.
+
+
+
+
+Templates
+=========
+
+- Indent with 4 spaces in general.
+
+- Embedded Python code follows the same conventions as in the backend.
+
+  A common problem are missed spaces around operators.
+
+
+
+
+Grunt AND npm2nix
+=================
+
+
+---something goes here ---
+
+
+
+
+LESS CSS
+========
+
+
+Style
+-----
+
+- Use 4 spaces instead of tabs.
+
+- Avoid ``!important``, it is very often an indicator for a problem.
+
+
+
+
+Structure
+---------
+
+It is important that we maintain consistency in the LESS files so that things
+scale properly. CSS is organized using LESS and then compiled into a css file
+to be used in production. Find the class you need to change and change it
+there. Do not add overriding styles at the end of the file. The LESS file will
+be minified; use plenty of spacing and comments for readability.
+
+These will be kept in auxillary LESS files to be imported (in this order) at the top:
+
+- `fonts.less` (font-face declarations)
+- `mixins` (place all LESS mixins here)
+- `helpers` (basic classes for hiding mobile elements, centering, etc)
+- `variables` (theme-specific colors, spacing, and fonts which might change later)
+
+
+Sections of the primary LESS file are as follows. Add comments describing
+layout and modules.
+
+.. code-block:: css
+
+   //--- BASE ------------------//
+           Very basic, sitewide styles.
+
+   //--- LAYOUT ------------------//
+           Essential layout, ex. containers and wrappers.
+           Do not put type styles in here.
+
+   //--- MODULES ------------------//
+           Reusable sections, such as sidebars and menus.
+
+   //--- THEME ------------------//
+           Theme styles, typography, etc.
+
+
+
+Formatting rules
+~~~~~~~~~~~~~~~~
+
+- Each rule should be indented on a separate line (this is helpful for diff
+  checking).
+
+- Use a space after each colon and a semicolon after each last rule.
+
+- Put a blank line between each class.
+
+- Nested classes should be listed after the parent class' rules, separated with a
+  blank line, and indented.
+
+- Using the below as a guide, place each rule in order of its effect on content,
+  layout, sizing, and last listing minor style changes such as font color and
+  backgrounds. Not every possible rule is listed here; when adding new ones,
+  judge where it should go in the list based on that hierarchy.
+
+  .. code-block:: scss
+
+     .class {
+             content
+             list-style-type
+             position
+             float
+             top
+             right
+             bottom
+             left
+             height
+             max-height
+             min-height
+             width
+             max-width
+             min-width
+             margin
+             padding
+             indent
+             vertical-align
+             text-align
+             border
+             border-radius
+             font-size
+             line-height
+             font
+             font-style
+             font-variant
+             font-weight
+             color
+             text-shadow
+             background
+             background-color
+             box-shadow
+             background-url
+             background-position
+             background-repeat
+             background-cover
+             transitions
+             cursor
+             pointer-events
+
+             .nested-class {
+                     position
+                     background-color
+
+                     &:hover {
+                             color
+                     }
+             }
+     }

docs/contributing/overview.rst

@@ -0,0 +1,111 @@
+
+=======================
+ Contributing Overview
+=======================
+
+
+RhodeCode Community Edition is an open source code management platform. We
+encourage contributions to our project from the community. This is a basic
+overview of the procedures for adding your contribution to RhodeCode.
+
+
+
+Check the Issue Tracker
+=======================
+
+Make an account at https://issues.rhodecode.com/account/register and browse the
+current tickets for bugs to fix and tasks to do. Have a bug or feature that you
+can't find in the tracker? Create a new issue for it. When you select a ticket,
+make sure to assign it to yourself and mark it "in progress" to avoid duplicated
+work. 
+
+
+
+Sign Up at code.rhodecode.com
+=============================
+
+Make an account at https://code.rhodecode.com/ using an email or your existing
+GitHub, Bitbucket, Google, or Twitter account. Fork the repo you'd like to
+contribute to; we suggest adding your username to the fork name. Clone your fork
+to your computer. We use Mercurial for source control management; see
+https://www.mercurial-scm.org/guide to get started quickly.
+
+
+
+Set Up A Local Instance
+=======================
+
+You will need to set up an instance of RhodeCode CE using VCSServer so that you
+can see your work locally as you make changes. We recommend using Linux for this
+but it can also be built on OSX.
+
+See :doc:`dev-setup` for instructions.
+
+
+
+Code!
+=====
+
+You can now make, see, and test your changes locally. We are always improving to
+keep our code clean and the cost of maintaining it low. This applies in the same
+way for contributions. We run automated checks on our pull requests, and expect
+understandable code. We also aim to provide test coverage for as much of our
+codebase as possible; any new features should be augmented with tests.
+
+Keep in mind that when we accept your contribution, we also take responsibility
+for it; we must understand it to take on that responsibility.
+
+See :doc:`standards` for more detailed information.
+
+
+
+Commit And Push Your Changes
+============================
+
+We highly recommend making a new bookmark for each feature, bug, or set of
+commits you make so that you can point to it when creating your pull request.
+Please also reference the ticket number in your commit messages. Don't forget to
+push the bookmark!
+
+
+
+Submit a Pull Request
+=====================
+
+Go to your fork, and choose "Create Pull Request" from the Options menu. Use
+your bookmark as the source, and choose someone to review it. Don't worry about
+chosing the right person; we'll assign the best contributor for the job. You'll
+get feedback and an assigned status.
+
+Be prepared to make updates to your pull request after some feedback.
+Collaboration is part of the process and improvements can often be made.
+
+
+
+Sign the Contributor License Agreement
+======================================
+
+If your contribution is approved, you will need to virtually sign the license
+agreement in order for it to be merged into the project's codebase. You can read
+it on our website here: https://rhodecode.com/static/pdf/RhodeCode-CLA.pdf
+
+To sign, go to code.rhodecode.com
+and clone the CLA repository. Add your name and make a pull request to add it to
+the contributor agreement; this serves as your virtual signature. Once your
+signature is merged, add a link to the relevant commit to your contribution
+pull request.
+
+
+
+That's it! We'll take it from there. Thanks for your contribution!
+------------------------------------------------------------------
+
+.. note:: If you have any questions or comments, feel free to contact us through
+          either the community portal(community.rhodecode.com), IRC
+          (irc.freenode.net), or Slack (rhodecode.com/join).
+
+
+
+
+
+

docs/contributing/standards.rst

@@ -0,0 +1,177 @@
+
+======================
+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!
+
+
+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 folder 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`