Table of contents¶

Definitions¶

Harassment includes, but is not limited to:

• Offensive comments related to gender, gender identity and expression, sexual orientation, disability, mental illness, neuro(a)typicality, physical appearance, body size, race, age, regional discrimination, political or religious affiliation
• Unwelcome comments regarding a person’s lifestyle choices and practices, including those related to food, health, parenting, drugs, and employment
• Deliberate misgendering. This includes deadnaming or persistently using a pronoun that does not correctly reflect a person’s gender identity. You must address people by the name they give you when not addressing them by their username or handle
• Physical contact and simulated physical contact (eg, textual descriptions like “hug” or “backrub”) without consent or after a request to stop
• Threats of violence, both physical and psychological
• Incitement of violence towards any individual, including encouraging a person to commit suicide or to engage in self-harm
• Deliberate intimidation
• Stalking or following
• Harassing photography or recording, including logging online activity for harassment purposes
• Sustained disruption of discussion
• Unwelcome sexual attention, including gratuitous or off-topic sexual images or behaviour
• Pattern of inappropriate social contact, such as requesting/assuming inappropriate levels of intimacy with others
• Continued one-on-one communication after requests to cease
• Deliberate “outing” of any aspect of a person’s identity without their consent except as necessary to protect others from intentional abuse
• Publication of non-harassing private communication

Our open source community prioritizes marginalized people’s safety over privileged people’s comfort. We will not act on complaints regarding:

• ‘Reverse’ -isms, including ‘reverse racism,’ ‘reverse sexism,’ and ‘cisphobia’
• Reasonable communication of boundaries, such as “leave me alone,” “go away,” or “I’m not discussing this with you”
• Refusal to explain or debate social justice concepts
• Communicating in a ‘tone’ you don’t find congenial
• Criticizing racist, sexist, cissexist, or otherwise oppressive behavior or assumptions

Diversity Statement¶

We encourage everyone to participate and are committed to building a community for all. Although we will fail at times, we seek to treat everyone both as fairly and equally as possible. Whenever a participant has made a mistake, we expect them to take responsibility for it. If someone has been harmed or offended, it is our responsibility to listen carefully and respectfully, and do our best to right the wrong.

Although this list cannot be exhaustive, we explicitly honor diversity in age, gender, gender identity or expression, culture, ethnicity, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, and technical ability. We will not tolerate discrimination based on any of the protected characteristics above, including participants with disabilities.

Reporting Issues¶

If you experience or witness unacceptable behavior—or have any other concerns—please report it by contacting us via hello@wearespindle.com. All reports will be handled with discretion. In your report please include:

• Your contact information.
• Names (real, nicknames, or pseudonyms) of any individuals involved. If there are additional witnesses, please

include them as well. Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly available record (e.g. a mailing list archive or a public IRC logger), please include a link. - Any additional information that may be helpful.

After filing a report, a representative will contact you personally, review the incident, follow up with any additional questions, and make a decision as to how to respond. If the person who is harassing you is part of the response team, they will recuse themselves from handling your incident. If the complaint originates from a member of the response team, it will be handled by a different member of the response team. We will respect confidentiality requests for the purpose of protecting victims of abuse.

Attribution & Acknowledgements¶

We all stand on the shoulders of giants across many open source communities. We’d like to thank the communities and projects that established code of conducts and diversity statements as our inspiration:

• Django
• Python
• Ubuntu
• Contributor Covenant
• Geek Feminism
• Citizen Code of Conduct

Basics¶

Let’s start with the basics; the coding style. You can check our ESLint rules in the .eslintrc file and the scss-lint rules in the .scss-lint.yml file. Both located in the root of the Lily app. Here’s a small excerpt of some general coding style rules.

Directives¶

Directives are used a lot in Lily. Most things we use more than a few times will get converted to a directives. Even a simple thing like displaying a date is a directive, because we want to be consistent throughout the whole application. Let’s take a random directive and break it down.

angular.module('app.directives').directive('editableSelect', editableSelect);

function editableSelect() {
    return {
        restrict: 'E',
        scope: {
            viewModel: '=',
            field: '@',
            type: '@',
            choiceField: '@',
            selectOptions: '=?', // contains any custom settings for the select
        },
        templateUrl: 'base/directives/editable_select.html',
        controller: EditableSelectController,
        controllerAs: 'es',
        transclude: true,
        bindToController: true,
    };
}

EditableSelectController.$inject = ['$scope', '$filter', 'HLResource'];
function EditableSelectController($scope, $filter, HLResource) {
    var es = this;

    es.getChoices = getChoices;
    es.updateViewModel = updateViewModel;

    activate();

    ...

    <other code>

Let’s start at the top.

angular.module('app.directives').directive('editableSelect', editableSelect);

We set up the module and say what name the directive has and what function we call to invoke the directive. The directive can then be used like this (as seen on the deals/controllers/detail.html page)

<editable-select field="next_step" view-model="vm" type="Deal">
    {{ vm.deal.next_step.name }}
</editable-select>

Once the directive is called it invokes the function editableSelect(). Let’s take the contents of that function and break it down (see comments).

return {
    // This directive can only be used as an HTML element (so by invoking <editable-select></editable-select>).
    restrict: 'E',
    // This directive has an isolated scope and accepts the following parameters:
    scope: {
        // Two way binded param. Changes to this param get reflected in the parent too.
        viewModel: '=',
        // One way binded param, so just pass the value so it can be used in this directive. Changes aren't reflected in the parent.
        field: '@',
        type: '@',
        choiceField: '@',
        // Two way binded optional param.
        selectOptions: '=?',
    },
    templateUrl: 'base/directives/editable_select.html', // The template to be used.
    controller: EditableSelectController, // The controller which contains any logic for this directive.
    controllerAs: 'es', // What variable is used to call the current directive. Is usually 'vm', but sometimes you want a clearer name.
    transclude: true, // Any content put between the directive's HTML tags will be put in the right spot in the template (covered later).
    bindToController: true,
};

The directive then knows what controller to use and calls that controller (EditableSelectController in this case).

// Inject any dependencies for this controller (such as utility functions).
EditableSelectController.$inject = ['$scope', '$filter', 'HLResource'];
function EditableSelectController($scope, $filter, HLResource) {
    // Set the controller's scope to an easier to use variable. Using `this` could given conflicts.
    var es = this;

    // Bind functions to the scope.
    es.getChoices = getChoices;
    es.updateViewModel = updateViewModel;

    // Not required, but used as an 'init' function for the controller.
    activate();

    ...

    <other code>

The rest of this directive’s code isn’t relevant and won’t be covered.

There’s one more thing we need to create a directive: the template. The template for the above controller isn’t very complicated and contains everything a normal template contains.

<span editable-select="es.selectModel" onshow="es.getChoices()" e-ng-options="item.id as item[es.optionDisplay] for item in es.choices"
      onbeforesave="es.updateViewModel($data)" buttons="no">
    <ng-transclude></ng-transclude>
</span>

This template might be confusing, but you can pretty much ignore all the attributes in the span tag. They are there to call a third party library (Angular x-editable), but you can see how the controller’s variables and function get used to set up the template. The ng-transclude you see is what I referred to in the intro to this directive. The {{ vm.deal.next_step.name }} is what will be put in the place of the ng-transclude. This transclusion allows you to have generic templates (like we do with the widget directive).

Note: Yes, another editableSelect directive gets called here, but this is the editableSelect provided by the Angular x-editable library.

Services¶

We use services to provide generic code to the app. Below is the HLResource service, which provides some useful functions related to resources.

// Make the service available and provide the name of the function which contains the logic.
angular.module('app.services').service('HLResource', HLResource);

// Inject any dependencies.
HLResource.$inject = ['$injector'];
function HLResource($injector) {
    this.patch = function(model, args) {
        // Function code.
    };

    ...

    <other code>
}

This function provides a generic way to PATCH a resource. It also provides generic error and success message once the request is done. An example of it’s usage can be found below.

// Inject the HLResource service.
DealDetailController.$inject = ['Deal', 'HLResource'];
function DealDetailController(Deal, HLResource) {
    // DealDetailController code.

    function updateModel() {
        // updateModel code.

        return HLResource.patch('Deal', args);
    }
}

Resources/Factories¶

To retrieve data from the backend and to share data across the app we use factories. Below is an excerpt of the Deal factory.

angular.module('app.deals.services').factory('Deal', Deal);

Deal.$inject = ['$resource', 'HLUtils', 'HLForms', 'User'];
function Deal($resource, HLUtils, HLForms, User) {
    // 'private' variable to show it's only supposed to be used in this scope.
    // Factory can be used by calling `Deal.<function>`.
    var _deal = $resource(
        '/api/deals/:id/',
        null,
        {
            // Overwrite the built-in patch function Angular provides so we can overwrite the transformRequest
            // and do stuff like cleaning our data.
            patch: {
                method: 'PATCH',
                params: {
                    id: '@id',
                },
                transformRequest: function () {
                    // transformRequest code.
                },
            },
            // Allows us to search deals through ElasticSearch.
            query: {
                url: '/search/search/',
                method: 'GET',
                params: {
                    // Set url GET parameters.
                    type: 'deals_deal',
                },
            },
            // This could be its own resource, but since it's so tightly connected to deals we just
            // provide it in the Deal service.
            getNextSteps: {
                url: 'api/deals/next-steps/',
            },
        }
    );

    return _deal;

Angular tips & tricks¶

This section provides a couple of tips & tricks which can save a lot of Googling and wondering why your code isn’t working.

if (vm.collapsableItems) {
    // Certain list widgets have collapsable cells, so set the default state to collapsed.
    if (!vm.list.hasOwnProperty('$promise')) {
        // Array was passed, so just pass the list.
        _setCollapsed(vm.list);
    } else {
        vm.list.$promise.then(function(response) {
            // List hasn't fully loaded, so wait and pass the response.
            _setCollapsed(response);
        });
    }
}