docs: more comprehensive contributor docs #4039

docs/contributing/checklist-tickets.rst

@@ -0,0 +1,137 b''
+.. _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/frontend.rst

@@ -0,0 +1,152 b''
+
+==================================================
+ 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 b''
+
+=======================
+ 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 b''
+
+======================
+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`

docs/contributing/contributing.rst

@@ -1,19 +1,20 b''
 .. _contributing:
 
 Contributing to RhodeCode
 =========================
 
 
 
 Welcome to the contribution guides and development docs of RhodeCode.
 
 
 
 .. toctree::
    :maxdepth: 1
 
+   overview
    testing/index
    dev-setup
    db-schema
    dev-settings
    api

docs/contributing/dev-setup.rst

@@ -1,143 +1,144 b''
+.. _dev-setup:
 
 ===================
  Development setup
 ===================
 
 
 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
 environment dependencies are correctly declared and installed during setup.
 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
 Enterprise running with isolation.
 
 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
 
 
 
 Setup Nix Package Manager
 -------------------------
 
 To install the Nix Package Manager, please run::
 
    $ curl https://nixos.org/nix/install | sh
 
 or go to https://nixos.org/nix/ and follow the installation instructions.
 Once this is correctly set up on your system, you should be able to use the
 following commands:
 
 * `nix-env`
 
 * `nix-shell`
 
 
 .. tip::
 
    Update your channels frequently by running ``nix-channel --upgrade``.
 
 
 Switch nix to the latest STABLE channel
 ---------------------------------------
 
 run::
 
    nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
 
 Followed by::
 
    nix-channel --update
 
 
 Clone the required repositories
 -------------------------------
 
 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
 RhodeCode VCSServer repositories into the same directory.
 To do this, use the following example::
 
     mkdir rhodecode-develop && cd rhodecode-develop
     hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
     hg clone https://code.rhodecode.com/rhodecode-vcsserver
 
 .. note::
 
    If you cannot clone the repository, please request read permissions
    via [e-mail]
 
 
 
 Enter the Development Shell
 ---------------------------
 
 The final step is to start the development shell. To do this, run the
 following command from inside the cloned repository::
 
    cd ~/rhodecode-enterprise-ce
    nix-shell
 
 .. note::
 
    On the first run, this will take a while to download and optionally compile
    a few things. The following runs will be faster. The development shell works
    fine on MacOS and Linux platforms.
 
 
 
 Creating a Development Configuration
 ------------------------------------
 
 To create a development environment for RhodeCode Enterprise,
 use the following steps:
 
 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
 2. Adjust the configuration settings to your needs
 
    .. note::
 
       It is recommended to use the name `dev.ini`.
 
 
 Setup the Development Database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To create a development database, use the following example. This is a one
 time operation::
 
     paster setup-rhodecode dev.ini \
         --user=admin --password=secret \
         --email=[e-mail] \
         --repos=~/my_dev_repos
 
 
 Start the Development Server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When starting the development server, you should start the vcsserver as a
 separate process. To do this, use one of the following examples:
 
 1. Set the `start.vcs_server` flag in the ``dev.ini`` file to true. For example:
 
    .. code-block:: python
 
       ### VCS CONFIG ###
       ##################
       vcs.start_server = true
       vcs.server = localhost:9900
       vcs.server.log_level = debug
 
    Then start the server using the following command: ``rcserver dev.ini``
 
 2. Start the development server using the following example::
 
       rcserver --with-vcsserver dev.ini
 
 3. Start the development server in a different terminal using the following
    example::
 
       vcsserver
 
 
 Run the Environment Tests
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Please make sure that the tests are passing to verify that your environment is
 set up correctly. RhodeCode uses py.test to run tests.
 Please simply run ``make test`` to run the basic test suite.