docs: more comprehensive contributor docs #4039
This commit is contained in:
lisaq
parent
0fcbe07fc9
commit
494b511b4c
6 changed files with 579 additions and 0 deletions
137
docs/contributing/checklist-tickets.rst
Normal file
137
docs/contributing/checklist-tickets.rst
Normal file
|
|
@ -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.
|
||||
|
||||
|
|
@ -12,6 +12,7 @@ Welcome to the contribution guides and development docs of RhodeCode.
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
overview
|
||||
testing/index
|
||||
dev-setup
|
||||
db-schema
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
.. _dev-setup:
|
||||
|
||||
===================
|
||||
Development setup
|
||||
|
|
|
|||
152
docs/contributing/frontend.rst
Normal file
152
docs/contributing/frontend.rst
Normal file
|
|
@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
111
docs/contributing/overview.rst
Normal file
111
docs/contributing/overview.rst
Normal file
|
|
@ -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).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
177
docs/contributing/standards.rst
Normal file
177
docs/contributing/standards.rst
Normal file
|
|
@ -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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue