diff --git a/docs/basics/skills.md b/docs/basics/skills.md index d8d02b7b..fcc7207f 100644 --- a/docs/basics/skills.md +++ b/docs/basics/skills.md @@ -30,10 +30,8 @@ accomplishing a particular development goal, certainly vary. - **PHP** - the main programming language in which CiviCRM is written - [Language reference](http://php.net/manual/en/langref.php) -- **Git** - a version control system for tracking changes to source code - - [Official documentation](https://git-scm.com/documentation) - - [15 minute interactive tutorial](https://try.github.io/levels/1/challenges/1) - - [Another site with more interactive tutorials](http://learngitbranching.js.org/) +- **Git, GitHub, and GitLab** - Git is a version control system for tracking changes to source code. GitHub and GitLab are web-based tools which host git repositories and issue-tracking systems. + - See [our recommended external resources](/tools/git.md#resources) - **Command line / bash** - in general, "the command line" refers to using a text-only interface to run programs such as `civix`, `git`, and many more. Bash is the most common "shell" program used to execute these commands on diff --git a/docs/core/contributing.md b/docs/core/contributing.md index 45f8803a..226f52a5 100644 --- a/docs/core/contributing.md +++ b/docs/core/contributing.md @@ -6,95 +6,22 @@ This chapter assumes that you have identified a bug or improvement for CiviCRM w This chapter will refer to a number of resources that are explained in greater depth in the [Developer Community](/basics/community.md) chapter. -## Check the latest version -There's no sense in planning any changes to CiviCRM's core code without looking at the most recent release. Any changes you make will be based upon it, and it may include a fix or attempted resolution that may change your thinking about the issue. +## Create an issue -It's best to start with upgrading your own site rather than just trying to use one with demo data. That way, you can be sure to know how the system behaves with your real-life data. +Creating a good issue is an important first step and often involves research, discussion, and thoughtful description. -If upgrading your site doesn't resolve it, try a plain installation of CiviCRM, such as one generated with Buildkit. This will ensure that your site-specific data isn't the problem, and having a plain vanilla site will be important for trying out your changes later. +[Following these comprehensive steps](/tools/issue-tracking.md#guidelines) to create your issue. -## Talk over the issue +## Document your change -To get your ideas together for later steps, it's best to start with a conversation. This doesn't need to be technical, but it should be with someone familiar with using CiviCRM. A coworker or consultant might be a place to start, or you could talk it over on [Mattermost](https://chat.civicrm.org/) or [Stack Exchange](http://civicrm.stackexchange.com/). - -In your conversation, think about some of the following questions: - -- How severe is the impact on organizations using CiviCRM? - -- Has this feature's behavior changed recently? Is a bug a regression, or has it always been this way? Is this a new feature that doesn't handle all situations properly? - -- Who might like things the way they are? Are there ways to resolve the issue that meet their needs as well as yours? - -- Will your change be self-explanatory, or will other users need an explanation? - -If you are able to coherently explain the problem and resolution—and reasonably confident that fix will be good for everyone—it's time to register the issue with CiviCRM. - -## Research existing issues - -It's now time to get your issue into [Jira](https://issues.civicrm.org/). To start, search for existing issues that may be the same as or related to yours. Jira's search will order by relevance, but you are searching over a decade of issues, so you may get overwhelmed with old items. Consider filtering Created Date to two years ago or newer. - -If an issue directly describes your situtation, your job will be different: read it over, and edit or comment as necessary. If the issue is marked as closed and completed, you should create a new issue indicating a regression, and you should link to the original issue you found. - -If issues you find are related but not quite the same, you should still record them so that you can mention them in the issue you create. - -## Describe the issue - -Now's the time to create your issue. Give it a title that describes your issue concisely, and explain the issue in the details. In writing your issue, remember that your audience includes a variety of people: - -- Other users encountering the same problem now -- Maintainers deciding whether to include your code -- Developers considering future changes -- The release notes editor compiling the notes -- Users browsing what's new in an upcoming version - -Readers will come from different perspectives and contexts, so thorough explanations and coherent summaries are valuable. A well-written issue will be taken more seriously, increasing the likelihood that your changes are accepted and that others engage in your issue. - -### Naming your issue - -*Vague issue titles are boring and unhelpful.* They don't inspire people to use or upgrade CiviCRM, and they make it difficult for implementors and developers to know what's different. Don't say "improve" unless the improvement is so scattered and subtle that you can't say anything else. Instead, make the specific improvements explicit. - -Bug titles are slightly different, but they still should never be vague. *A good bug title simply says the bad thing that's happening.* Great examples include the following: - -- "Batch merge redirects users to snippet URL" -- "Contribution page: missing translation" -- "Cannot create smart group from 'Find participants'" - -The best leave no question as to what was going wrong or what has changed: something undesirable was happening, and once this issue is resolved, it won't happen anymore. - -### Issue scope - -*It's important to keep your issue snappy and closeable.* A Jira issue that stays open long after commits have been merged into core is confusing to users and demoralizing for contributors. The way to prevent this is to make issues distinct and coherent so they're clearly done or not done. - -Better yet, describe the issue distinctly and coherently yourself. If you find an existing issue that was reported vaguely, there's no reason not to revise the description. If the original issue involves several things, don't be shy about closing it and opening new ones--just document what you've done. - -A rule of thumb is that if an issue has more than 2 or 3 pull requests in GitHub (described below), something is wrong. It may be a series of false starts, and that's okay, but if it's a bunch of pull requests against the same repository, you probably should have opened new issues to describe the separate features or bugs—or to document a regression or feature gap. - -### Categorization - -Categorization is useful for finding issues in Jira, and it also determines how issues appear in the release notes. - -When setting the issue **Type**, "Bug" results in it being listed among Bugs Resolved in the release notes. Otherwise, issues appear in Features. - -The **Component/s** field determines where the issue goes in the notes, but it will only go one place. There's no value in saying something is "Accounting Integration", "CiviContribute", "CiviEvent", and "WordPress Integration": the editor will pick the most relevant one for the notes. - -The **Priority** field can get contentious, but use your best sense as to the impact that your issue will have. Think of it as the product of the breadth (the size of the user base that may notice) and depth (how much those users are affected) of the issue. - -**Affects Version/s** doesn't need to be each and every version that the problem affects, but it is helpful to indicate the extent of it. Include the latest version you tested it on, and include the earliest version in the stable and long-term support series you know it to affect. - -You might wonder what the **Funding Source** means. If you plan on writing code yourself, mark it as "Contributed Code". Otherwise, mark it as "Needs Funding". - -## Document the feature - -Now that you have an issue created, you can start work. The best place to begin is to document what you want to happen. By writing the documentation first, you have a way to measure whether the feature works. - -If you're addressing a bug, document the feature that the bug affects. You may find documentation in the [User and Administrator Guide](https://docs.civicrm.org/user/en/stable/), or you may have to start from scratch. Either way, save what you do and contribute it back to the guide once you're finished. +Your changes might require documentation updates. Read about [when to document](/documentation/index.md#when) and [how to document](/documentation/index.md#contributing) and follow steps as necessary. ## Write tests -Having a plain-language description of how things should work in hand, it's time to operationalize the description and build automated tests for the feature. CiviCRM comes with a variety of [testing tools](https://wiki.civicrm.org/confluence/display/CRMDOC/Testing) that help ensure that changes don't break existing functionality. +Having a plain-language description of how things should work in hand, it's time to operationalize the description and build automated tests for the feature. CiviCRM comes with a variety of [testing tools](/testing/setup.md) that help ensure that changes don't break existing functionality. -Since CiviCRM doesn't release code with failing tests, your bug or improvement must not be covered in the existing tests. Maybe there are incomplete tests, maybe the tests aren't valid measures of the functionality, or maybe your feature lacks test coverage. Either way, you will need to write them to make sure your work doesn't get undermined by future changes. +Since CiviCRM [doesn't release code with failing tests](/tools/jenkins.md), your bug or improvement must not be covered in the existing tests. Maybe there are incomplete tests, maybe the tests aren't valid measures of the functionality, or maybe your feature lacks test coverage. Either way, you will need to write them to make sure your work doesn't get undermined by future changes. Use your documentation to identify tests that can be run, and then write them. If you are adding functionality, you may not have the code that the test will call, but you can write your tests as if all the pages and functions exist, defining them later. @@ -106,21 +33,21 @@ The key in making changes is legibility: helping others see what you've changed ### Coding style -One element of legibility is literal: make your changes according to the [CiviCRM coding standards](https://wiki.civicrm.org/confluence/display/CRMDOC/PHP+Code+and+Inline+Documentation), which are just a relaxed version of [Drupal's standards](https://www.drupal.org/docs/develop/standards). This doesn't just make the code more readable on its own; standards make the diff more legible too. +One element of legibility is literal: make your changes according to the [CiviCRM coding standards](/standards/index.md). This doesn't just make the code more readable on its own; standards make the diff more legible too. -Each pull request is automatically tested by PHP_CodeSniffer according to [the standards](https://github.com/civicrm/coder), and you should save time and test your code yourself. +Each pull request is [automatically tested](/tools/jenkins.md) by PHP_CodeSniffer according to [the standards](https://github.com/civicrm/coder), and you should save time and test your code yourself. ### Making commits -In making commits, remember that this isn't just a small personal project: your audience is hundreds of other developers—now and ten years from now—as well as end users trying to understand features and bugs. By leaving a commit history that makes sense—both in content and in [commit messages](https://wiki.civicrm.org/confluence/display/CRMDOC/Git+Commit+Messages+for+CiviCRM)—you will make the code more legible for everyone. +Follow these steps to [make high-quality commits](/tools/git.md#committing). Once you've completed the work, revisit your documentation and tests to see if you've missed anything. ## Open a pull request -Open a pull request on GitHub to merge your development branch with the `master` branch. Check that the title makes sense and that the description indicates what's going on. Pull request titles don't need to be identical to issue titles, and in particular, you may want to focus more positively on the changes in code than on the broader feature changes. +Read about [creating a pull request](/tools/git.md#pr) which includes information on writing a good subject line and minding the scope of your PR. -Once you submit your pull request, CiviCRM's Jenkins server will build a copy of CiviCRM and run tests against it, beginning with PHP_CodeSniffer. If tests fail, you will be able to follow a link to view details. +Once you submit your pull request, CiviCRM's [Jenkins server](/tools/jenkins.md) will build a copy of CiviCRM and run tests against it, beginning with `PHP_CodeSniffer`. If tests fail, you will be able to follow a link to view details. Other developers may comment on your code, raising questions or concerns or marking the changes as approved. This is fine, but it is important not to hide important discussion. If substantive discussion occurs in a pull request, note it in Jira. If a pull request is closed in favor of another, explain that in Jira and mention the old pull request in the new one. @@ -130,7 +57,7 @@ The goal is that the next person working on this feature area shouldn't have to While your pull request is reviewed, and even after it is merged, you will need to maintain your code on the site that needed the changes. There are two main techniques for this. -First, you can keep your `civicrm` directory under version control, including your changes there. If you need to upgrade while your changes are still in review, rebase your changes on top of the new version. +First, you can keep your `civicrm` directory under version control, including your changes there. If you need to upgrade while your changes are still in review, [rebase](/tools/git.md#rebase) your changes on top of the new version. Alternatively, you can use a custom PHP or template override directory. While this is generally discouraged for long-term customizations of your site (extensions are better), it can be an efficient way to track short-term overrides. Just declare the path to the custom PHP and template folders in the Administer - System Settings - Directories page and copy your changed file(s) there, placing them under the same directory structure as within the `civicrm-core` repository. Note the issue number and pull request in a comment at the top of each file, and remember to check the directory each time you upgrade. Once your change is merged, just delete the override. diff --git a/docs/core/develop.md b/docs/core/develop.md deleted file mode 100644 index 019b14a2..00000000 --- a/docs/core/develop.md +++ /dev/null @@ -1,31 +0,0 @@ -# Developing CiviCRM - -## Repositories - -CiviCRM is divided into a few repositories. This allows developers to work -with different components, allows different teams to manage each component, -and will allow all the pieces to be remixed using different tools (civibuild, -shell scripts, Drush & Drush make, or composer). The repositories are: - -- [civicrm-core](https://github.com/civicrm/civicrm-core/) - - Core application which can be embedded in different systems - (Drupal, Joomla, etc). -- [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/) - - Drupal integration modules, with branches for each CiviCRM release & - Drupal major version (e.g. 7.x-4.6, 7.x-4.7, 6.x-4.4, 6.x-4.6). -- [civicrm-joomla](https://github.com/civicrm/civicrm-joomla/) - - Joomla integration modules. -- [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) - - WordPress integration modules. -- [civicrm-backdrop](https://github.com/civicrm/civicrm-backdrop/) - - Backdrop integration module. -- [civicrm-packages](https://github.com/civicrm/civicrm-packages/) - - External dependencies required by CiviCRM. -- [civicrm-l10n](https://github.com/civicrm/civicrm-l10n/) - - Localization data. - -## Obtaining a development build of CiviCRM - -The recommended method is to use -[CiviCRM Buildkit](https://github.com/civicrm/civicrm-buildkit/) to build a -CiviCRM codebase to develop with. diff --git a/docs/core/pr-review.md b/docs/core/pr-review.md index 5689e54a..06d6fbc4 100644 --- a/docs/core/pr-review.md +++ b/docs/core/pr-review.md @@ -1,6 +1,6 @@ # How to review a core pull request -When someone [opens a pull request](/core/contributing.md#open-a-pull-request) (aka "PR") on CiviCRM Core, it must be reviewed before we can merge it. Reviewing core PRs is a useful (and often much-needed) way of contributing to CiviCRM. You do not need any special access or merge rights. What you do need, is... +When someone [opens a pull request](/tools/git.md#pr) (aka "PR") on CiviCRM Core, it must be reviewed before we can merge it. Reviewing core PRs is a useful (and often much-needed) way of contributing to CiviCRM. You do not need any special access or merge rights. What you do need, is... * [GitHub Account](https://github.com) * A [CiviCRM Development Environment](https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md) (this might be optional, but good to have). One benefit is the ability to check out the PR in your environment. diff --git a/docs/core/release-process.md b/docs/core/release-process.md new file mode 100644 index 00000000..667e0ac6 --- /dev/null +++ b/docs/core/release-process.md @@ -0,0 +1,11 @@ +# Review/Release Process + +Releases are developed on a monthly cycle. At the start of the month, the +release-manager will send an invitation to developers who have open PRs, +encouraging them to participate in the release-cycle. Participation +provides a way to exchange feedback with other developers, get PRs merged, +and ensure the next release works -- all with a predictable timeline. + +* For a high-level summary of the release process, see the [Release Management README](https://github.com/civicrm/release-management/blob/master/README.md). +* For an example invitation, see the previous [invitation for the April-May 2016](https://github.com/civicrm/release-management/issues/1). + diff --git a/docs/documentation/index.md b/docs/documentation/index.md index a64f3e31..1f77abed 100644 --- a/docs/documentation/index.md +++ b/docs/documentation/index.md @@ -12,6 +12,23 @@ This page describes the details of the documentation systems within CiviCRM and [migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide [wiki]: https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation + +## When to document {:#when} + +If you are [contributing to core](/core/contributing.md), updating documenting along with your changes is an important step to ensure the long-term usability and maintainability of CiviCRM. + +Not all changes require documentation updates. Here are some guidelines: + +* Documentation should almost always accompany **new features**. + * Keep in mind that some features are user-facing (and thus require new documentation in the User Guide) whereas some features are *developer*-facing (and thus require new documentation in the Developer Guide.) +* Bug fixes will occasionally require documentation updates. Check existing docs to see what changes might be necessary. + +!!! tip + Try writing documentation *before* writing your code! Then you have a way to organize your thoughts and measure whether the feature works. + +If you are [submitting a core pull request](/tools/git.md#pr) and would like to submit accompanying doc changes, please provide comments in both pull requests for cross reference. Your docs PR will not be merged until your core PR is merged first. + + ## Guides in MkDocs We are using [MkDocs](http://www.mkdocs.org) to produce guides. The content for each of these guides is written in [markdown](/documentation/markdown.md), stored in text files, and hosted in a repository on GitHub. Then, the guides are automatically published to [docs.civicrm.org](https://docs.civicrm.org) using our custom [publishing system](https://github.com/civicrm/civicrm-docs). @@ -31,7 +48,7 @@ In rarer cases, if you have an edit that pertains to a specific version, (e.g. d A guide can have multiple languages, and we use separate repositories for different languages. For example, you can click *See all X editions* and find the repositories for additional languages. -## Contributing to documentation +## Contributing to documentation {:#contributing} We welcome contributions, small and large, to documentation! diff --git a/docs/standards/index.md b/docs/standards/index.md index fbc442d2..05b7bfb7 100644 --- a/docs/standards/index.md +++ b/docs/standards/index.md @@ -28,7 +28,7 @@ In general, CiviCRM follow's the [Drupal Coding Standards](https://www.drupal.or ## Continuous integration -Jenkins will automatically check all pull requests for coding standards conformance, and code which does not meet the standards will not be merged. +[Jenkins](/tools/jenkins.md) will automatically check all pull requests for coding standards conformance, and code which does not meet the standards will not be merged. ## Tools diff --git a/docs/testing/manual.md b/docs/testing/manual.md new file mode 100644 index 00000000..eac4ce7c --- /dev/null +++ b/docs/testing/manual.md @@ -0,0 +1,295 @@ +# Manual testing + +Due to the varied nature of environments & the implicitly incomplete coverage automated tests have manual testing will never be obsolete. This page contains links to some test plans to be mixed & matched for RC testing + + +## Dedupe and merge testing {:#dedupe} + +### Finding duplicates + +1. Choose a rule to dedupe on, do not filter by a group, check that all + potential duplicates are displayed +1. As above, but enter a 'limit', ensure that the number of results is + limited to no more than the number specified +1. Choose a rule to dedupe on, filter by a group, check that the list + of potential duplicates is fewer + +### Manually merging records + +Click to **Merge** two records using the interface. + +1. Check that clicking **Next** takes you to the next record expected +1. Check that clicking **Previous** takes you to the previous record +1. Check that clicking **Flip** flips the positions of the *main* and + *duplicate* contacts + +Check the manual merge UI when choosing information and contact details +to merge across. + +1. Check that when changing an email 'type' the value on the right + changes to display the email address currently associated with that + record +1. Check that the merge type (eg: 'add' or 'overwrite') changes when + the box is ticked + +Merge the records, and check that records merged correctly. + +1. Check that the duplicate was deleted +1. Check that any core information 'ticked' to be migrated was migrated + across +1. Check that location fields were 'added' or 'overwritten' as + appropriate, into any new 'types' that were specified +1. Check that attached information (such as mailings, groups, CMS + user accounts) were migrated successfully if ticked to migrate + +### Batch merging records + +From the dedupe listing screen. + +1. Tick and batch merge a pair of contacts that can be merged + without conflict. Check they are merged correctly: + - No duplicate phone numbers or email addresses created (eg: two + home@home.com email address in the home type) +1. Tick and batch merge a pair of contacts that would cause a + merge conflict: + - Check that they are not merged, and you are taken to the + 'conflicts' screen + - Force merge them, and check that they are merged (no + duplicate phone numbers or email addresses) +1. 'Flip' a pair of contacts and then 'batch merge' them. Check that + the new 'duplicate' record is still the duplicate and is deleted + +### Merge from the contact search 'task' list + +- Perform a contact search, select two contacts and choose the 'Merge' + task: Ensure you are taken to the 'Merge' screen for the contacts. + +### Merging by code (API) + +*Not yet documented* + + +## Smart group testing {:#smart-group} + +#### General use cases + +- Run advanced search by name=Adams. Create a smart group. Check + group membership. +- Run advanced search by name=Bachman. Create a smart group. Check + group membership. +- Edit a contact, changing last name to Adams. Check group membership. + Observe new member. +- Edit a contact, changing last name away from Adams. Check + group membership. Observe removed member. +- Add a contact with last name Bachman. Check group membership. + Observe new member. +- Delete a contact with last name Bachman. Check group membership. + Observe missing member. +- Update definition of group Bachman to filter on + contact_type=Individual. Check group membership. Observe removed + member (household "Bachman family"). + +#### Confounding Factors + +Smart groups are cached. The caching behavior is influenced by a couple +options: + +- `smartGroupCacheTimeout`: Time-to-live (e.g. "retain the cached list of members for 5 minutes") +- `smart_group_cache_refresh_mode`: Refresh-mode + - "opportunistic": (e.g. "flush stale caches whenever data changes") + - "deterministic": (e.g. "flush stale caches using a cron job") + +You may experience slightly different behaviors depending what was +cached before, how you time the steps, and which options are chosen. + +Think of it this way; each general use-case includes the step "Check +group membership". As part of that step, you might initially see a stale +list of members. To force it to display an actual list, you might wait 5 +minutes (to pass the TTL) **OR** hack `civicrm_group.cache_date` to +set an earlier expiration. + +If your main interest is browsing the list of members through the UI, +then (in my experience) it's not necessary to explicitly run the cron +job. When you look at a group in the UI, it checks the staleness and +updates the cache (if it's expired). + +However, if your main interest is testing the nuances of refresh-modes, +then you should *not* check the list of members through the UI. Instead: + +- Repeatedly use SQL to inspect the content of `civicrm_group` and `civicrm_group_contact_cache` +- For opportunistic mode, trigger a flush by editing some unrelated contact. +- For deterministic cron mode, trigger a flush by calling `Job.group_cache_flush` API. + +!!! bug "Wishlist" + + For testing/inspection purposes, it would help to update the list screen ("Contacts in Group" aka "civicrm/group/search"): + + - Display the timestamp for when the cache was generated + - Provide a button to force the cache to regenerate + + +## Tarball installation testing {:#tarball} + +If you are testing a release-candidate or specifically working on the +installation subsystem, then you may need to try some of the manual +testing processes below. + +### Picking tarballs + +- For official tarballs, browse [civicrm.org/download](http://civicrm.org/download) +- For unofficial nightly tarballs, browse + [download.civicrm.org/latest](https://download.civicrm.org/latest) +- For a pending pull-request, you must build custom tarballs + +To make custom tarballs from a pull request, you need to run +`distmaker` which requires a special file structure and some config +files, but `civibuild` can automated that. For example: + +1. Checkout the code for the pull request. (In this example, it uses civicrm-core.git#8177.) + + ```bash + $ civibuild create dist --url http://dist.localhost --patch https://github.com/civicrm/civicrm-core/pull/8177 + ``` + +1. Run distmaker + + ```bash + $ cd $HOME/buildkit/build/dist/src/distmaker + $ ./distmaker.sh all + ``` + +1. Observe the output + + ```bash + $ ls $HOME/buildkit/build/dist/out/tar + ``` + +### Option 1. Fully manual installation and upgrade + +You can, of course, follow the normal instructions for [Installation and +Upgrades](/confluence/display/CRMDOC/Installation+and+Upgrades). + +If you're not big into scripting/CLI, this is the way to go. But it can +be time-consuming. + +### Option 2. Upgrade a staging site with "drush cvup" + +If you have a Drupal staging site with CiviCRM already installed, you can use `drush` to load a tarball. + +Formula: + +```bash +drush cvup --tarfile= --backupdir= +``` + +1. Navigate to your site + + ```bash + $ cd /var/www/drupal + ``` + +1. Clear caches + + ```bash + $ drush cc all + ``` + +1. Download and extract an official CiviCRM tarball + + ```bash + $ wget http://download.civicrm.org/civicrm-4.7.7-drupal.tar.gz -O /tmp/civicrm-4.7.7-drupal.tar.gz + $ drush cvup --tarfile=/tmp/civicrm-4.7.7-drupal.tar.gz --backupdir=/tmp/myupgrade + ``` + +1. OR... Extract a custom CiviCRM tarball + + ```bash + $ drush cvup --tarfile=$HOME/buildkit/build/dist/out/tar/civicrm-4.7.7-drupal.tar.gz --backupdir=/tmp/myupgrade + ``` + +1. Clear caches + + ```bash + $ rm -rf sites/default/files/civicrm/templates_c/ + $ sdrush cc all + ``` + +Also see this [StackExchange question](http://civicrm.stackexchange.com/questions/4829/is-it-easy-to-upgrade-civicrm-using-drush). + +### Option 3. Create an empty site with "civibuild" + +If you don't have a staging site, you can use [civibuild](/tools/civibuild.md) +to create empty sites for Drupal, WordPress, and Backdrop and preload +the tarball. This will cue the system so that it's ready for you to go +the installation screen. + + +1. Create an empty Drupal test site. Download and extract a CiviCRM tarball. Display login details. + + ```bash + $ civibuild create dempty --type drupal-empty --url http://dempty.localhost --dl sites/all/modules=http://download.civicrm.org/civicrm-4.7.7-drupal.tar.gz + ``` + +1. Cleanup a test site + + ```bash + $ civibuild destroy dempty + ``` + +See [civibuild](/tools/civibuild.md) for more options. + +!!! note + At time of writing, this supports Drupal 7, WordPress, and Backdrop. + +### Option 4. Create a batch of sites with "civihydra" (experimental) + +This is a lot like Option 3, but it loops through all the tarballs and runs `civibuild` for each of them. + +Formula: + +```bash +civihydra create +``` + +1. Create D7, WordPress, and Backdrop sites using official tarballs. Display login details. + + ```bash + civihydra create http://download.civicrm.org/civicrm-4.7.7-{drupal.tar.gz,wordpress.zip,backdrop-unstable.tar.gz} + ``` + +1. OR... create D7, WordPress, and Backdrop sites using your own custom tarballs. Display login details. + + ```bash + civihydra create $HOME/buildkit/build/dist/out/tar/* + ``` + +1. Cleanup all the test sites + + ```bash + civihydra destroy + ``` + +!!! note + At time of writing, this supports Drupal 7, WordPress, and Backdrop. + +### See also: Headless installation testing for civibuild and git + +If you use [civibuild](/tools/civibuild.md), then you most likely setup the local source tree using a conventional +configuration like `drupal-demo` or `wp-demo`. This downloads the +pristine code from git and performs an automated installation and enables a convenient development loop: + +1. Write a patch +1. Run `civibuild reinstall `. +1. Check the outcome +1. (Repeat as necessary) +1. Commit and open a pull request + +!!! note + In addition to re-running the installation, you can also test the DB upgrades by running "`civibuild upgrade-test `". For more information about the available commands, see [civibuild](/tools/civibuild.md). + +This is convenient for most development but has a downside: Most admins +use the web-based graphical installer included with the tarballs (with a +filtered version of the source tree). Consequently, the automated +installation is not quite as representative of how a typical admin +works. + diff --git a/docs/tools/git.md b/docs/tools/git.md new file mode 100644 index 00000000..23d79afc --- /dev/null +++ b/docs/tools/git.md @@ -0,0 +1,275 @@ +# Git, GitHub, and GitLab + +CiviCRM uses git, GitHub, and GitLab to manage changes to the code. A solid understanding of these tools (especially git) is important for developing CiviCRM. This page provides some information about *how CiviCRM uses these tools* — but, due to the wealth of resources already available elsewhere online, this page does *not* attempt to teach you everything you need know about how to use these tools for CiviCRM development. + +!!! tip + If you are new to git, a great way to get started using it within the CiviCRM community is to [contribute to documentation](/documentation/index.md). The editing workflow involves git in the same was that core coding does — but the stakes are much lower! + +## External resources {:#resources} + +* Git + * [Official documentation](https://git-scm.com/documentation) + * [15 minute interactive tutorial](https://try.github.io/levels/1/challenges/1) + * [Another site with more interactive tutorials](http://learngitbranching.js.org/) +* GitHub + * [Official help site](https://help.github.com/) + * [20 minute GitHub tutorial video](https://www.youtube.com/watch?v=0fKg7e37bQE) + * [hub](https://hub.github.com/) - a useful commandline tool for GitHub which can speed up your workflow +* GitLab + * [Official documentation](https://docs.gitlab.com/ce/README.html) + + +## Repositories + +* GitHub - **[github.com/civicrm](https://github.com/civicrm/)** + * As of 2017, most of CiviCRM's repositories are hosted on GitHub + * Most of the repositories hosted on GitHub are owned by the "CiviCRM" organization. + * Here are some of the most important repositories hosted on GitHub + * [civicrm-core](https://github.com/civicrm/civicrm-core/) - Core application which can be embedded in different systems (Drupal, Joomla, etc). + * [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/) - Drupal integration modules, with branches for each CiviCRM release & Drupal major version (e.g. 7.x-4.6, 7.x-4.7, 6.x-4.4, 6.x-4.6). + * [civicrm-joomla](https://github.com/civicrm/civicrm-joomla/) - Joomla integration modules. + * [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) - WordPress integration modules. + * [civicrm-backdrop](https://github.com/civicrm/civicrm-backdrop/) - Backdrop integration module. + * [civicrm-packages](https://github.com/civicrm/civicrm-packages/) - External dependencies required by CiviCRM. + * [civicrm-l10n](https://github.com/civicrm/civicrm-l10n/) - Localization data. + * *...and [many others](https://github.com/civicrm/) too!* + +* GitLab - **[lab.civicrm.org/explore/projects](http://lab.civicrm.org/explore/projects)** + * CiviCRM also has some repositories hosted on this self-hosted installation of GitLab + + +## Git workflow overview {:#contributing} + +Whether you are contributing to civicrm-core or an ancillary project (using GitHub or GitLab) the process generally goes somewhat like this: + +1. (If working on core) [open an issue on Jira](/tools/issue-tracking.md#jira) to describe the change you'd like to make. +1. Find the page on GitHub or GitLab for the project to which you would like to contribute. We will call this repository the **upstream repository**. +1. **Clone** the upstream repository to your local machine. (If you are working on core, you should use [civibuild](/tools/civibuild.md) for this step.) +1. On the web page for the upstream repository, **fork** the upstream repository to your personal user account. +1. Within your local repository **add your fork** as a second git *remote*. *[Learn more...](#remotes)* +1. **Choose the correct base branch** in the upstream repository as the starting point for your changes. (Usually this will be `master`.) *[Learn more...](#base-branch)* +1. (If it's been some time since you've cloned) **pull or fetch** the latest changes from the *upstream repository* into the appropriate branch of your local repository. *(You might also need to [upgrade your civibuild site](/tools/civibuild.md#upgrade-site).)* +1. Create (and checkout) a **new branch** for your changes, based on the correct branch (chosen above) in the upstream repository. *[Learn more...](#branching)* +1. Make your changes. (Take care to follow the guidelines in [contributing to core](/core/contributing.md).) +1. **Commit** your changes. *[Learn more...](#commiting)* +1. **Push** your changes *to your fork*. +1. **Open a pull request**. *[Learn more...](#pr)* +1. Wait for someone else to [review your pull request](/core/pr-review.md). +1. If you need to make more changes later, commit them on the same branch and push your new commits to your fork. The new commits the will automatically appear in the pull request. +1. If other people commit changes to the upstream repository which create *merge conflicts* in your pull request, then **rebase** your branch. *[Learn more...](#rebasing)* +1. Once your changes are merged, delete your local branch + +See also: [reviewing someone else's pull request](/core/pr-review.md) + + +## Pull requests {:#pr} + +!!! note "terminology" + The terms "pull request", "merge request", "PR", and "MR" all effectively synonymous. GitHub uses "pull request", and GitLab uses "merge request". + +### Creating a pull request {:#pr-submit} + +1. In the web browser, navigate to the web page for your fork (e.g. `https://github.com/myuser/civicrm-core` ) +1. Click **Pull Request** +1. There will be two branches specified – the (first) left should be "civicrm" (i.e. where the code is going to). The second (right) should be your branch. +1. Add a [good subject](#pr-subject) and explanation, and submit. + +### Writing a pull request subject {:#pr-subject} + +Pull request titles don't need to be identical to issue titles, and in particular, you may want to focus more positively on the changes in code than on the broader feature changes. Here are some guidelines for writing a good subject line: + +When filing a pull-request, use a descriptive subject. These are good examples: + + * `CRM-12345 - Fix Paypal IPNs when moon is at half-crescent (waxing)` + * `(WIP) CRM-67890 - Refactor SMS callback endpoint` + * `(NFC) CRM_Utils_PDF - Improve docblocks` + +A few elements to include: + + * **CRM-_XXXXX_** - This is a reference to the [Jira issue tracker](/tools/issue-tracking.md#jira). A bot will setup crosslinks between JIRA and GitHub. + * **Description** - Provide a brief description of what the pull-request does. + * **(WIP)** - "Work in Progress" - If you are still developing a set of + changes, it may be useful to submit a pull-request and flag it as + `(WIP)`. This allows you to have discussion with other developers and + check test results. Once the change is ready, update the subject line + to remove `(WIP)`. + * **(NFC)** - "Non-Functional Change" - Most patches are designed to + change functionality (e.g. fix an error message or add a new button). + However, some changes are non-functional -- e.g. they cleanup the + code-style, improve the comments, or improve the test-suite. + +### Pull request scope {:#pr-scope} + +A good pull request addresses a clearly-defined problem. There should be a detailed description logged in the [issue tracker](http://issues.civicrm.org/). Excellent PRs also increase test coverage. If you are tempted to do additional tweaks or code cleanup outside the scope of that issue, you could make a separate commit and include them in the PR if they are minor & non-controversial, or create a seperate PR if they are more complex. + +There is no size limit for PRs as long as they are focused on completely solving a discreet problem. As a practical matter, though, bigger PRs may take longer to review and merge. When possible, split "epic" issues into bite-sized chunks as long as each seperate PR is functionally complete and does not cause merge conflicts with your other PRs. In the latter case, add commits to an existing PR. + +### Reviewing a pull request + +See [How to review a core pull request](/core/pr-review.md) + +### Who merges pull requests {:#pr-merge} + +A person may be granted the privilege/responsibility of reviewing and merging pull requests who: + +* Is an active contributor to the CiviCRM project. +* Responds to communications in a timely fashion. +* Is familiar with current CiviCRM coding standards and best practices. +* Is a careful proofreader and tester, and who gives thorough constructive feedback. + + +## Git tasks + +### Cloning {:#cloning} + +When you want to set up a local copy of a git repo hosted on GitHub or GitLab, you *clone* it. Here are two ways: + +* Using the SSH protocol + + ```bash + $ git clone git@github.com:civicrm/civicrm-core.git + ``` + +* Using the HTTP protocol + + ```bash + $ git clone https://github.com/civicrm/civicrm-core.git + ``` + +Using SSH is a little bit better because you won't need to enter your password all the time, but it does require some [extra steps](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). + +### Managing multiple git remotes {:#remotes} + +Your local git repo is typically set up to track at least one *remote* git repo for operations like `fetch`, `pull`, and `push`. But it can be helpful to set up multiple remotes when contributing to repos which you don't own. + +Common terminology: + +* **Upstream repository** - a repo hosted on GitHub or GitLab which *you don't own* but would like to contribute to +* **Fork repository** - a repo hosted on GitHub or GitLab which *you own* and have created by "forking" an upstream repo +* **Local repository** - the repo that lives on your local computer after [cloning](#cloning) + +Show the remotes which your local repo is tracking: + +```bash +$ git remote -v +upstream https://github.com/civicrm/civicrm-core.git (fetch) +upstream https://github.com/civicrm/civicrm-core.git (push) +myusername git@github.com:myusername/civicrm-core.git (fetch) +myusername git@github.com:myusername/civicrm-core.git (push) +``` + +The first column shown in the output is the *name* of the remote. You can rename your remotes however you want. Assuming your GitHub user name is `myusername`, the above output looks pretty good because we have two remotes: one named `upstream` (an *upstream repo*), and another named `myusername` (a *fork repo*). When you first [clone](#cloning) a repository, git will set up a remote called `origin` which refers to the repo you initially cloned. In the above example we don't see `origin`, so that remote has been removed or renamed. + +Read about [how to use `git remote`](https://git-scm.com/docs/git-remote) to properly set up your remotes. + +!!! tip + If you use [hub](https://hub.github.com/), the command `hub clone` can help with this + + + +### Branching {:#branching} + +Git uses branches to separate independent sets of changes. When creating a new branch, here are some things to keep in mind: + +* [Choose an appropriate base branch](#base-branch) +* You'll need to keep your local branch until its changes are merged. Sometimes this can take several months. After it's merged, you can delete it. +* Give your branch a good name + * The name of your branch is up to you. + * It should be unique among your other outstanding branches. + * It should only contain letters, numbers, dashes, and underscores. + * If you have a Jira issue, you can use its number (e.g `CRM-1234`) as the name of the branch. + +Create a new branch and switch your local repository to it: + +```bash +$ git checkout upstream/master -b CRM-1234 +``` + +* `upstream` is your local name for the [git remote](#remotes) which represents the upstream repository (e.g. `https://github.com/civicrm/civicrm-core`) to which you are contributing changes. Depending on how you have set up your local repo, this remote might have a different name, like `origin` or `civicrm`. +* `master` is the name of the branch in the upstream repository on which you would like to base your changes +* `CRM-1234` is the name of your new branch + +### Choosing a base branch {:#base-branch} + +When creating a new branch, you should explicitly declare a starting point. + +Most of the time, your base branch should be `master`. However, CiviCRM core keeps two main branches under active development: `master` (for the latest version), *and* another branch for the current LTS release (as listed on [civicrm.org/download](https://civicrm.org/download)). For example, if you have a client running the LTS version (e.g. `4.6`) then any changes you make to `master` will not affect this client until they do a major upgrade. In this case you may wish to "backport" a change to the LTS version and choose the `4.6` branch as your base branch. + +### Committing {:#committing} + +As much as possible, separate your changes into distinct commits that each make sense on their own. Using smaller commits will make your changes easier for others to review. + +#### Writing a commit message {:#commit-messages} + +When making commits, remember that this isn't just a small personal project: your audience is hundreds of other developers — now and ten years from now — as well as end users trying to understand features and bugs. By leaving a commit history that makes sense — both in content and in commit messages — you will make the code more legible for everyone. + +Follow these guidelines to write a good commit messages: + +* The first line should be a meaningful **subject**, which should: + * be prefixed with a Jira issue number (if the commit is to CiviCRM core) + * mention a "subsystem" after the issue number + * be 72 characters or less, in total + * be in "Sentence case" + * use the imperative mood + * not end in a period + * examples: + * `CRM-20600 - Civi\Angular - Generate modules via AssetBuilder` + * `CRM-19417 - distmaker - Change report to JSON` +* (optionally but recommended) After the subject, include a short **body**, which should: + * have a blank line above it (below the subject) + * be wrapped at 72 characters + * explain *what*, *why*, and *how* + +### Rebasing {:#rebasing} + +Sometimes when you [make a pull request](#pr) someone else merges a change into the upstream repository that *conflicts* with your change. The best way to resolve this conflict is to rebase. It's a good idea to [read about rebasing](https://git-scm.com/docs/git-rebase) so you understand the theory. Here's the practice: + +!!! note + In this example we have two [remotes](#remotes) set up: + + * `upstream` which tracks the upstream repo + * `myusername` which tracks the fork repo + + Also we are working on changes in a branch called `my-branch` + +1. Update your local `master` branch + + ```bash + $ git checkout master + $ git pull upstream master + ``` + +1. Checkout the branch that has conflicts you'd like to resolve + + ```bash + $ git checkout my-branch + $ git rebase master + ``` + +1. See which files need attention + + ```bash + $ git status + ``` + +1. Make changes to the files which resolve the merge conflicts + +1. "Add" the files to tell git you have resolved the conflicts + + ```bash + $ git add CRM/Utils/String.php + ``` + +1. Continue the rebase + + ```bash + $ git rebase --continue + ``` + +1. Force-push your changes back up to your fork + + ```bash + $ git push -f myusername my-branch + ``` + +1. Now, if you go to back to the page for your pull request it should no longer show merge conflicts diff --git a/docs/tools/github.md b/docs/tools/github.md deleted file mode 100644 index 71bb855d..00000000 --- a/docs/tools/github.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using GitHub for CiviCRM development - -TODO: migrate content from - -https://wiki.civicrm.org/confluence/display/CRMDOC/Contributing+to+CiviCRM+using+GitHub diff --git a/docs/tools/issue-tracking.md b/docs/tools/issue-tracking.md new file mode 100644 index 00000000..32cacfc8 --- /dev/null +++ b/docs/tools/issue-tracking.md @@ -0,0 +1,133 @@ +# Issue-tracking systems + +As of 2017 CiviCRM uses three different system for tracking and managing issues (aka tickets). This page offers a brief summary of the systems and helps developers understand when and how to use them. + + +## Systems + +### Jira {:#jira} + +**[issues.civicrm.org](https://issues.civicrm.org/jira)** + +Used as an issue-tracking system for: + +* **[CiviCRM core](https://issues.civicrm.org/jira/browse/CRM)** +* [CiviVolunteer](https://issues.civicrm.org/jira/browse/VOL) +* [CiviHR](https://issues.civicrm.org/jira/browse/HR) +* *...and a small number of [other projects](https://issues.civicrm.org/jira/secure/BrowseProjects.jspa?selectedCategory=all&selectedProjectType=all)* + +### GitHub {:#github} + +**[github.com/civicrm](https://github.com/civicrm)** + +Used as an issue-tracking system for: + +* [buildkit](https://github.com/civicrm/civicrm-buildkit/issues) +* [cv](https://github.com/civicrm/cv/issues) +* [civix](https://github.com/totten/civix) +* *...and many [other projects](https://github.com/civicrm)* + +!!! note + Some projects (e.g. CiviCRM core) have their repository hosted on GitHub but do *not* use the GitHub issue-tracking functionality. For these projects you will notice there is no "Issues" tab. + + +### GitLab {:#gitlab} + +**[lab.civicrm.org](http://lab.civicrm.org)** + +Used as an issue-tracking system for: + +* [civicrm.org website issues](https://lab.civicrm.org/marketing-team/civicrm-website) +* [infrastructure issues](https://lab.civicrm.org/infrastructure/ops/issues) +* *...and some [other projects](https://lab.civicrm.org/explore/projects)* + +In 2017, CiviCRM began to use a private GitLab installation for *some* projects. + + +## Guidelines for creating issues {:#guidelines} + +### When to create an issue {:#when-to-create} + +All changes to CiviCRM *Core*, however small, must receive a Jira issue. Among other things, this helps us assemble the [release notes](https://github.com/civicrm/civicrm-core/tree/master/release-notes). + +For other (non-core) ancillary projects, it's okay [submit a pull request](/tools/git.md#pr) *without* first creating an issue. + +### Check the latest version {:#check-version} + +There's no sense in planning any changes to CiviCRM's core code without looking at the most recent release. Any changes you make will be based upon it, and it may include a fix or attempted resolution that may change your thinking about the issue. + +It's best to start with upgrading your own site rather than just trying to use one with demo data. That way, you can be sure to know how the system behaves with your real-life data. + +If upgrading your site doesn't resolve it, try a plain installation of CiviCRM, such as one generated with Buildkit. This will ensure that your site-specific data isn't the problem, and having a plain vanilla site will be important for trying out your changes later. + +### Talk over the issue {:#talk} + +To get your ideas together for later steps, it's best to start with a conversation. This doesn't need to be technical, but it should be with someone familiar with using CiviCRM. A coworker or consultant might be a place to start, or you could talk it over on [Mattermost](https://chat.civicrm.org/) or [Stack Exchange](http://civicrm.stackexchange.com/). + +In your conversation, think about some of the following questions: + +- How severe is the impact on organizations using CiviCRM? + +- Has this feature's behavior changed recently? Is a bug a regression, or has it always been this way? Is this a new feature that doesn't handle all situations properly? + +- Who might like things the way they are? Are there ways to resolve the issue that meet their needs as well as yours? + +- Will your change be self-explanatory, or will other users need an explanation? + +If you are able to coherently explain the problem and resolution—and reasonably confident that fix will be good for everyone—it's time to register the issue with CiviCRM. + +### Research existing issues {:#research} + +It's now time to get your issue into [Jira](https://issues.civicrm.org/). To start, search for existing issues that may be the same as or related to yours. Jira's search will order by relevance, but you are searching over a decade of issues, so you may get overwhelmed with old items. Consider filtering Created Date to two years ago or newer. + +If an issue directly describes your situation, your job will be different: read it over, and edit or comment as necessary. If the issue is marked as closed and completed, you should create a new issue indicating a regression, and you should link to the original issue you found. + +If issues you find are related but not quite the same, you should still record them so that you can mention them in the issue you create. + +### Describe the issue {:#describe} + +Now's the time to create your issue. Give it a title that describes your issue concisely, and explain the issue in the details. In writing your issue, remember that your audience includes a variety of people: + +- Other users encountering the same problem now +- Maintainers deciding whether to include your code +- Developers considering future changes +- The release notes editor compiling the notes +- Users browsing what's new in an upcoming version + +Readers will come from different perspectives and contexts, so thorough explanations and coherent summaries are valuable. A well-written issue will be taken more seriously, increasing the likelihood that your changes are accepted and that others engage in your issue. + +#### Naming your issue {:#naming} + +*Vague issue titles are boring and unhelpful.* They don't inspire people to use or upgrade CiviCRM, and they make it difficult for implementors and developers to know what's different. Don't say "improve" unless the improvement is so scattered and subtle that you can't say anything else. Instead, make the specific improvements explicit. + +Bug titles are slightly different, but they still should never be vague. *A good bug title simply says the bad thing that's happening.* Great examples include the following: + +- "Batch merge redirects users to snippet URL" +- "Contribution page: missing translation" +- "Cannot create smart group from 'Find participants'" + +The best leave no question as to what was going wrong or what has changed: something undesirable was happening, and once this issue is resolved, it won't happen anymore. + +#### Issue scope {:#scope} + +*It's important to keep your issue snappy and closeable.* A Jira issue that stays open long after commits have been merged into core is confusing to users and demoralizing for contributors. The way to prevent this is to make issues distinct and coherent so they're clearly done or not done. + +Better yet, describe the issue distinctly and coherently yourself. If you find an existing issue that was reported vaguely, there's no reason not to revise the description. If the original issue involves several things, don't be shy about closing it and opening new ones--just document what you've done. + +A rule of thumb is that if an issue has more than 2 or 3 pull requests in GitHub (described below), something is wrong. It may be a series of false starts, and that's okay, but if it's a bunch of pull requests against the same repository, you probably should have opened new issues to describe the separate features or bugs—or to document a regression or feature gap. + +See also: [pull request scope](/tools/git.md#pr-scope) + +#### Categorization {:#categorization} + +Categorization is useful for finding issues in Jira, and it also determines how issues appear in the release notes. + +When setting the issue **Type**, "Bug" results in it being listed among Bugs Resolved in the release notes. Otherwise, issues appear in Features. + +The **Component/s** field determines where the issue goes in the notes, but it will only go one place. There's no value in saying something is "Accounting Integration", "CiviContribute", "CiviEvent", and "WordPress Integration": the editor will pick the most relevant one for the notes. + +The **Priority** field can get contentious, but use your best sense as to the impact that your issue will have. Think of it as the product of the breadth (the size of the user base that may notice) and depth (how much those users are affected) of the issue. + +**Affects Version/s** doesn't need to be each and every version that the problem affects, but it is helpful to indicate the extent of it. Include the latest version you tested it on, and include the earliest version in the stable and long-term support series you know it to affect. + +You might wonder what the **Funding Source** means. If you plan on writing code yourself, mark it as "Contributed Code". Otherwise, mark it as "Needs Funding". diff --git a/docs/tools/jenkins.md b/docs/tools/jenkins.md new file mode 100644 index 00000000..18f341f9 --- /dev/null +++ b/docs/tools/jenkins.md @@ -0,0 +1,21 @@ +# Jenkins continuous integration + +Pull-requests are tested automatically with build-bot software called [Jenkins](https://jenkins.io/) which runs on [tests.civicrm.org](http://tests.civicrm.org/). Key things to know: + +* If you are a new contributor, the tests may be placed on hold pending a + cursory review. One of the administrators will post a comment like + `jenkins, ok to test` or `jenkins, add to whitelist`. +* The pull-request will have a colored dot indicating its status: + * **Yellow**: The automated tests are running. + * **Red**: The automated tests have failed. + * **Green**: The automated tests have passed. +* If the automated test fails, click on the red dot to investigate details. Check for information in: + * The initial summary. Ordinarily, this will list test failures and error messages. + * The console output. If the test-suite encountered a significant error (such as a PHP crash), + the key details will only appear in the console. +* Code-style tests are executed first. If the code-style in this patch is inconsistent, the remaining tests will be skipped. +* The primary tests may take 20-120 min to execute. This includes the following suites: `api_v3_AllTests`, `CRM_AllTests`, `Civi\AllTests`, `civicrm-upgrade-test`, and `karma` +* There are a handful of unit tests which are time-sensitive and which fail sporadically. See: https://forum.civicrm.org/index.php?topic=36964.0 +* The web test suite (`WebTest_AllTests`) takes several hours to execute. [It runs separately -- after the PR has been merged.](https://test.civicrm.org/job/CiviCRM-WebTest-Matrix/) + +For detailed discussion about automated tests, see [Testing](/testing/setup.md) diff --git a/mkdocs.yml b/mkdocs.yml index c1391f4a..06187dd6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,12 +18,14 @@ pages: - civibuild: tools/civibuild.md - cividist: tools/cividist.md - civilint: tools/civilint.md - - GitHub: tools/github.md + - Issue Tracking: tools/issue-tracking.md + - Git, GitHub, & GitLab: tools/git.md + - Jenkins: tools/jenkins.md - PhpStorm: tools/phpstorm.md - Debugging: tools/debugging.md - Core Development: - When to Edit Core: core/hacking.md - - Developing CiviCRM: core/develop.md + - Release process: core/release-process.md - How to Contribute: core/contributing.md - Reviewing PR's: core/pr-review.md - Codebase & Architecture: core/architecture.md @@ -55,6 +57,7 @@ pages: - "Selinium Tests": testing/selinium.md - "Continuous Integration": testing/continuous-integration.md - "Upgrade Tests": testing/upgrades.md + - Manual Testing: testing/manual.md - Framework Reference: - AngularJS: - "AngularJS: Intro": framework/angular/index.md diff --git a/redirects/internal.txt b/redirects/internal.txt index 144c5b93..540411fb 100644 --- a/redirects/internal.txt +++ b/redirects/internal.txt @@ -7,3 +7,4 @@ api/general api hooks/hook_civicrm_trigger_info hooks/hook_civicrm_triggerInfo framework/schema-definition framework/database/schema-definition api/params api/options +core/develop tools/git diff --git a/redirects/wiki-crm.txt b/redirects/wiki-crm.txt index 15eae643..a1af4864 100644 --- a/redirects/wiki-crm.txt +++ b/redirects/wiki-crm.txt @@ -1,4 +1,5 @@ Documentation+Infrastructure+Canary develop Book+style+guide best-practices/documentation-style-guide CiviCRM+Unit+Testing+basic+information testing/setup -Writing+a+PHPUnit+testcase+HOWTO testing/setup \ No newline at end of file +Writing+a+PHPUnit+testcase+HOWTO testing/setup +Pull-Request+Process tools/git/#pr diff --git a/redirects/wiki-crmdoc.txt b/redirects/wiki-crmdoc.txt index e4a45a58..5e2df34f 100644 --- a/redirects/wiki-crmdoc.txt +++ b/redirects/wiki-crmdoc.txt @@ -168,3 +168,9 @@ Section+elements framework/ui Database+layer standards/database Using+Custom+Data+with+the+API api/custom-data CiviReport+Reference reference/civireport +Manual+testing testing/manual +Dedupe+and+merge+testing testing/manual/#dedupe +Smart+group+testing testing/manual/#smart-group +Tarball+installation+testing testing/manual/#tarball +Contributing+to+CiviCRM+using+GitHub tools/git/#github +Git+Commit+Messages+for+CiviCRM tools/git/#committing