diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/changelog.md | 1 | ||||
| -rw-r--r-- | doc/development/ee_features.md | 14 | ||||
| -rw-r--r-- | doc/development/emails.md | 18 | ||||
| -rw-r--r-- | doc/development/gitaly.md | 73 |
4 files changed, 102 insertions, 4 deletions
diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 1962392a9eb..d5a4acff481 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -44,6 +44,7 @@ the `author` field. GitLab team members **should not**. - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. Example: "Fixed a typo on the search results page. (Jane Smith)" +- Performance improvements **should** have a changelog entry. ## Writing good changelog entries diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 3ba03d2d591..287143d6255 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -644,6 +644,7 @@ information on managing page-specific javascript within EE. To separate EE-specific styles in SCSS files, if a component you're adding styles for is limited to only EE, it is better to have a separate SCSS file in appropriate directory within `app/assets/stylesheets`. +See [backporting changes](#backporting-changes) for instructions on how to merge changes safely. In some cases, this is not entirely possible or creating dedicated SCSS file is an overkill, e.g. a text style of some component is different for EE. In such cases, @@ -683,6 +684,19 @@ to avoid conflicts during CE to EE merge. // EE-specific end ``` +### Backporting changes from EE to CE + +When working in EE-specific features, you might have to tweak a few files that are not EE-specific. Here is a workflow to make sure those changes end up backported safely into CE too. +(This approach does not refer to changes introduced via [csslab](https://gitlab.com/gitlab-org/csslab/).) + +1. **Make your changes in the EE branch.** If possible, keep a separated commit (to be squashed) to help backporting and review. +1. **Open merge request to EE project.** +1. **Apply the changes you made to CE files in a branch of the CE project.** (Tip: Use `patch` with the diff from your commit in EE branch) +1. **Open merge request to CE project**, referring it's a backport of EE changes and link to MR open in EE. +1. Once EE MR is merged, the MR towards CE can be merged. **But not before**. + +**Note:** regarding SCSS, make sure the files living outside `/ee/` don't diverge between CE and EE projects. + ## gitlab-svgs Conflicts in `app/assets/images/icons.json` or `app/assets/images/icons.svg` can diff --git a/doc/development/emails.md b/doc/development/emails.md index 4dbf064fd75..73cac82caf0 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -74,6 +74,24 @@ See the [Rails guides] for more info. 1. Reply by email should now be working. +## Email namespace + +If you need to implement a new feature which requires a new email handler, follow these rules: + + - You must choose a namespace. The namespace cannot contain `/` or `+`, and cannot match `\h{16}`. + - If your feature is related to a project, you will append the namespace **after** the project path, separated by a `+` + - If you have different actions in the namespace, you add the actions **after** the namespace separated by a `+`. The action name cannot contain `/` or `+`, , and cannot match `\h{16}`. + - You will register your handlers in `lib/gitlab/email/handler.rb` + +Therefore, these are the only valid formats for an email handler: + + - `path/to/project+namespace` + - `path/to/project+namespace+action` + - `namespace` + - `namespace+action` + +Please note that `path/to/project` is used in GitLab Premium as handler for the Service Desk feature. + --- [Return to Development documentation](README.md) diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 26abf967dcf..4f9ca1920a5 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -7,6 +7,67 @@ be replaced by Gitaly API calls. Visit the [Gitaly Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341) for current status of the migration. +## Developing new Git features + +Starting with Gitlab 10.8, all new Git features should be developed in +Gitaly. + +> This is a new process that is not clearly defined yet. If you want +to contribute a Git feature and you're getting stuck, reach out to the +Gitaly team or `@jacobvosmaer-gitlab`. + +By 'new feature' we mean any method or class in `lib/gitlab/git` that is +called from outside `lib/gitlab/git`. For new methods that are called +from inside `lib/gitlab/git`, see 'Modifying existing Git features' +below. + +There should be no new code that touches Git repositories via +disk access (e.g. Rugged, `git`, `rm -rf`) anywhere outside +`lib/gitlab/git`. + +The process for adding new Gitaly features is: + +- exploration / prototyping +- design and create a new Gitaly RPC [in gitaly-proto](https://gitlab.com/gitlab-org/gitaly-proto) +- release a new version of gitaly-proto +- write implementation and tests for the RPC [in Gitaly](https://gitlab.com/gitlab-org/gitaly), in Go or Ruby +- release a new version of Gitaly +- write client code in gitlab-ce/ee, gitlab-workhorse or gitlab-shell that calls the new Gitaly RPC + +These steps often overlap. It is possible to use an unreleased version +of Gitaly and gitaly-proto during testing and development. + +- See the [Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/CONTRIBUTING.md#development-and-testing-with-a-custom-gitaly-proto) for instructions on writing server side code with an unreleased protocol. +- See [below](#running-tests-with-a-locally-modified-version-of-gitaly) for instructions on running gitlab-ce tests with a modified version of Gitaly. +- In GDK run `gdk install` and restart `gdk run` (or `gdk run app`) to use a locally modified Gitaly version for development + +### Gitaly-ruby + +It is possible to implement and test RPC's in Gitaly using Ruby code, +in +[gitaly-ruby](https://gitlab.com/gitlab-org/gitaly/tree/master/ruby). +This should make it easier to contribute for developers who are less +comfortable writing Go code. + +There is documentation for this approach in [the Gitaly +repo](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md). + +## Modifying existing Git features + +If you modify existing Git features in `lib/gitlab/git` you need to make +sure the changes also work in Gitaly. Because we are still in the +migration process there are a number of subtle pitfalls. Features that +have been migrated have dual implementations (Gitaly and local). The +Gitaly implementation may or may not use a vendored (and therefore +possibly outdated) copy of the local implementation in `lib/gitlab/git`. + +To avoid unexpected problems and conflicts, all changes to +`lib/gitlab/git` need to be approved by a member of the Gitaly team. + +For the time being, while the Gitaly migration is still in progress, +there should be no Enterprise Edition-only Git code in +`lib/gitlab/git`. Also no mixins. + ## Feature Flags Gitaly makes heavy use of [feature flags](feature_flags.md). @@ -99,10 +160,14 @@ end ## Running tests with a locally modified version of Gitaly -Normally, gitlab-ce/ee tests use a local clone of Gitaly in `tmp/tests/gitaly` -pinned at the version specified in GITALY_SERVER_VERSION. If you want -to run tests locally against a modified version of Gitaly you can -replace `tmp/tests/gitaly` with a symlink. +Normally, gitlab-ce/ee tests use a local clone of Gitaly in +`tmp/tests/gitaly` pinned at the version specified in +`GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports +`=my-branch` syntax to use a custom branch in gitlab-org/gitaly. If +you want to run tests locally against a modified version of Gitaly you +can replace `tmp/tests/gitaly` with a symlink. This is much faster +because the `=my-branch` syntax forces a Gitaly re-install each time +you run `rspec`. ```shell rm -rf tmp/tests/gitaly |