diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/contributing/index.md | 7 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 48 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 55 | ||||
| -rw-r--r-- | doc/development/ee_features.md | 5 | ||||
| -rw-r--r-- | doc/development/fe_guide/vue.md | 6 | ||||
| -rw-r--r-- | doc/development/fe_guide/vuex.md | 4 | ||||
| -rw-r--r-- | doc/development/gitaly.md | 4 | ||||
| -rw-r--r-- | doc/development/testing_guide/best_practices.md | 6 |
8 files changed, 66 insertions, 69 deletions
diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index b39c302453b..8b1d014e101 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -3,9 +3,6 @@ Thank you for your interest in contributing to GitLab. This guide details how to contribute to GitLab in a way that is easy for everyone. -We want to create a welcoming environment for everyone who is interested in contributing. -Please visit our [Code of Conduct page](https://about.gitlab.com/contributing/code-of-conduct) to learn more about our commitment to an open and welcoming environment. - For a first-time step-by-step guide to the contribution process, please see ["Contributing to GitLab"](https://about.gitlab.com/contributing/). @@ -33,8 +30,8 @@ vulnerabilities. ## Code of conduct -Our code of conduct can be found on the -["Contributing to GitLab"](https://about.gitlab.com/contributing/) page. +We want to create a welcoming environment for everyone who is interested in contributing. +Please visit our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/) to learn more about our commitment to an open and welcoming environment. ## Closing policy for issues and merge requests diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index a4da34a50ce..4a2ff64807e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -48,29 +48,21 @@ as its markdown rendering engine. See the [GitLab Markdown Guide](https://about. Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. -## Documentation directory structure +## Documentation types and organization The documentation is structured based on the GitLab UI structure itself, separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), [`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). -In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, -all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. - -The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have -been **deprecated** and the majority their docs have been moved to their correct location -in small iterations. Please do not create new docs in these folders. Organize docs by product area and subject, not type. +Organize docs by product area and subject, not type. For example, do not create groupings of similar media types +(e.g. indexes of all articles, videos, etc.). -### Documentation files - -- When you create a new directory, always start with an `index.md` file. - Do not use another file name and **do not** create `README.md` files. -- **Do not** use special chars and spaces, or capital letters in file names, - directory names, branch names, and anything that generates a path. -- Max screenshot size: 100KB. -- We do not support videos (yet). +Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes +it difficult to browse for the information you need and difficult to maintain up-to-date content. +Instead, organize content by its subject (e.g. everything related to CI goes together) +and cross-link between any related content. -### Location and naming documents +### Location and naming of files Our goal is to have a clear hierarchical structure with meaningful URLs like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, @@ -78,16 +70,8 @@ you can immediately tell that you are navigating to user-related documentation about project features; specifically about merge requests. Our site's paths match those of our repository, so the clear structure also makes documentation easier to update. -While the documentation is home to a variety of content types, we do not organize by content type. -For example, do not create groupings of similar media types (e.g. indexes of all articles, videos, etc.). -Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes -it difficult to browse for the information you need and difficult to maintain up-to-date content. -Instead, organize content by its subject (e.g. everything related to CI goes together) -and cross-link between any related content. - -Do not simply link out to GitLab technical blog posts. There should be an up-to-date -single source of truth on the topic within the documentation, and the top of the -blog post should be updated to link to that doc. +In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, +all docs should be linked at least from its higher-level index page if not also from other relevant locations. The table below shows what kind of documentation goes where. @@ -102,13 +86,18 @@ The table below shows what kind of documentation goes where. | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | | `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | -**General rules & best practices:** +**Rules and best practices:** +1. When you create a new directory, always start with an `index.md` file. + Do not use another file name and **do not** create `README.md` files. +1. **Do not** use special chars and spaces, or capital letters in file names, + directory names, branch names, and anything that generates a path. 1. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (`-`). For example, a proper naming would be `import_projects_from_github.md`. The same rule applies to images. -1. Start a new directory with an `index.md` file. +1. For image files, do not exceed 100KB. +1. We do not yet support embedded videos. Please link out. 1. There are four main directories, `user`, `administration`, `api` and `development`. 1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, `profile/`, `dashboard/` and `admin_area/`. @@ -129,6 +118,9 @@ The table below shows what kind of documentation goes where. 1. The `doc/topics/` directory holds topic-related technical content. Create `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. +1. The directories `/workflow/`, `/university/`, and `/articles/` have +been **deprecated** and the majority their docs have been moved to their correct location +in small iterations. If you are unsure where a document or a content addition should live, this should not stop you from authoring and contributing. You can use your best judgment and diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index c0386290785..1cefe48b4c1 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -14,9 +14,8 @@ For programmatic help adhering to the guidelines, see [linting](index.md#linting ## Files -- [Directory structure](index.md#location-and-naming-documents): place the docs - in the correct location. -- [Documentation files](index.md#documentation-files): name the files accordingly. +See the [Documentation types and organization](index.md#documentation-types-and-organization) section +on the index page for information on how to structure and name files across the GitLab documentation. DANGER: **Attention:** **Do not** use capital letters, spaces, or special chars in file names, @@ -28,41 +27,43 @@ a test that will fail if it spots a new `README.md` file. ### Markdown -The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) -in October 2018. +The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its Markdown rendering engine [as of October 2018](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108). For a complete Kramdown reference, see the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) gem will support all [GFM markup](../../user/markdown.md) in the future. For now, -use regular markdown markup, following the rules on this style guide. For a complete -Kramdown reference, check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). -Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in -[`/help`](index.md#gitlab-help). +use regular markdown markup, following the rules in the linked style guide. + +Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly in on GitLab instances in [`/help`](index.md#gitlab-help). ## Content These guidelines help toward the goal of having every user's search of documentation yield a useful result, and ensuring content is helpful and easy to consume. -- What to include: - - Any and all helpful information, processes, and tips for implementing, - using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) - for this information. - - 'Risky' or niche problem-solving steps. There is no reason to withhold these or - store them elsewhere; simply include them along with the rest of the docs including all necessary - detail, such as specific warnings and caveats about potential ramifications. - - Any content types/sources, if relevant to users or admins. You can freely - include presentations, videos, etc.; no matter who it was originally written for, - if it is helpful to any of our audiences, we can include it. If an outside source - that's under copyright, rephrase, or summarize and link out; do not copy and paste. - - All applicable subsections as described on the [structure and template](structure.md) page, - with files organized in the [correct directory](index.md#documentation-directory-structure). +### Subject matter + +[The documentation is the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) for any and all helpful information and processes needed to learn about, implement, use, and troubleshoot GitLab features. Note that this includes problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided. See the SSOT link for more detail. + +### Media types and sources + +Include any media types/sources, if relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. + + - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. + - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. + +### Structure across documents + +- Place files in the correct directory per the [Documentation directory structure](index.md#documentation-types-and-organization) guidelines. +- To avoid duplication, do not include the same information in multiple places. Instead, choose one 'single source of truth (SSOT)' location and link from other relevant locations. +- When referencing other GitLab products and features, link to their respective docs. +- When referencing third-party products or technologies, link out to their external sites, documentation, and resources. + +### Structure within documents + +- Include any and all applicable subsections as described on the [structure and template](structure.md) page, - To ensure discoverability, link to each doc from its higher-level index page and other related pages. -- When referencing other GitLab products and features, link to their - respective docs; when referencing third-party products or technologies, - link out to their external sites, documentation, and resources. -- Do not duplicate information. - Structure content in alphabetical order in tables, lists, etc., unless there is - a logical reason not to (for example, when mirroring the UI or an ordered sequence). + a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence). ## Language diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 9452593c510..c5a1d915be6 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -19,6 +19,11 @@ CE specs should remain untouched as much as possible and extra specs should be added for EE. Licensed features can be stubbed using the spec helper `stub_licensed_features` in `EE::LicenseHelpers`. +You can force Webpack to act as CE by either deleting the `ee/` directory or by +setting the [`IS_GITLAB_EE` environment variable](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/config/helpers/is_ee_env.js) +to something that evaluates as `false`. The same works for running tests +(for example `IS_GITLAB_EE=0 yarn jest`). + [ee-as-ce]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2500 ## Separation of EE code diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index a34d1fcec89..437ce9abc7d 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -38,7 +38,7 @@ _For consistency purposes, we recommend you to follow the same structure._ Let's look into each of them: -### A `index.js` file +### An `index.js` file This is the index file of your new feature. This is where the root Vue instance of the new feature should be. @@ -46,7 +46,7 @@ of the new feature should be. The Store and the Service should be imported and initialized in this file and provided as a prop to the main component. -Don't forget to follow [these steps][page_specific_javascript]. +Be sure to read about [page-specific JavaScript][page_specific_javascript]. ### Bootstrapping Gotchas #### Providing data from HAML to JavaScript @@ -240,7 +240,7 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards [environments-table]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/environments -[page_specific_javascript]: https://docs.gitlab.com/ce/development/frontend.html#page-specific-javascript +[page_specific_javascript]: ./performance.md#page-specific-javascript [component-system]: https://vuejs.org/v2/guide/#Composing-with-Components [state-management]: https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch [one-way-data-flow]: https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 7b54fa6289c..7d52cac5f7e 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -83,7 +83,7 @@ In this file, we will write the actions that will call the respective mutations: export const requestUsers = ({ commit }) => commit(types.REQUEST_USERS); export const receiveUsersSuccess = ({ commit }, data) => commit(types.RECEIVE_USERS_SUCCESS, data); - export const receiveUsersError = ({ commit }, error) => commit(types.REQUEST_USERS_ERROR, error); + export const receiveUsersError = ({ commit }, error) => commit(types.RECEIVE_USERS_ERROR, error); export const fetchUsers = ({ state, dispatch }) => { dispatch('requestUsers'); @@ -175,7 +175,7 @@ Remember that actions only describe that something happened, they don't describe state.users = data; state.isLoading = false; }, - [types.REQUEST_USERS_ERROR](state, error) { + [types.RECEIVE_USERS_ERROR](state, error) { state.isLoading = false; }, [types.REQUEST_ADD_USER](state, user) { diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 27b69ba8278..bfde26dbe4a 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -6,7 +6,7 @@ Workhorse and GitLab-Shell. ## Beginner's guide Start by reading the gitaly repository's -[Beginner's guide to Gitaly contributions](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/beginners_guide.md). +[Beginner's guide to Gitaly contributions](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/beginners_guide.md). It describes how to setup gitaly, the various components of gitaly and what they do, and how to run its test suites. ## Developing new Git features @@ -192,7 +192,7 @@ GITALY_REPO_URL=https://gitlab+deploy-token-1000:token-here@gitlab.com/nick.thom To use a custom Gitaly repository in CI, for instance if you want your GitLab fork to always use your own Gitaly fork, set `GITALY_REPO_URL` -as a [CI environment variable](../ci/variables/README.md#variables). +as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment-variables). --- diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 7262c04d746..e41148360f2 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -216,8 +216,10 @@ project, one project will do for the entire file. This can be achieved by using reloads or recreates the model, _only_ if needed. That is, when you changed properties or destroyed the object. -There is one gotcha; you can't reference a model defined in a `let` block in a -`set` block. +Note that you can't reference a model defined in a `let` block in a `set` block. + +Also, `set` is not supported in `:js` specs since those don't use transactions +to clean up database state after each example. ### Time-sensitive tests |