diff --git a/docs/contributing/checklist-tickets.rst b/docs/contributing/checklist-tickets.rst new file mode 100644 --- /dev/null +++ b/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. + diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rst --- a/docs/contributing/contributing.rst +++ b/docs/contributing/contributing.rst @@ -12,6 +12,7 @@ Welcome to the contribution guides and d .. toctree:: :maxdepth: 1 + overview testing/index dev-setup db-schema diff --git a/docs/contributing/dev-setup.rst b/docs/contributing/dev-setup.rst --- a/docs/contributing/dev-setup.rst +++ b/docs/contributing/dev-setup.rst @@ -1,3 +1,4 @@ +.. _dev-setup: =================== Development setup diff --git a/docs/contributing/frontend.rst b/docs/contributing/frontend.rst new file mode 100644 --- /dev/null +++ b/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 + } + } + } diff --git a/docs/contributing/overview.rst b/docs/contributing/overview.rst new file mode 100644 --- /dev/null +++ b/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). + + + + + + diff --git a/docs/contributing/standards.rst b/docs/contributing/standards.rst new file mode 100644 --- /dev/null +++ b/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 `_ +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 `_. +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 `_ + + +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`