Contribution Guidelines

Contributing

Thank you for your interest in contributing to the APPSeCONNECT!

The document covers the process for contributing to the articles and code samples that are hosted on the APPSeCONNECT Documentation site. Contributions may be as simple as typo corrections or as complex as new articles.

• Process for contributing
• DOs and DON'Ts

This repository contains the conceptual documentation for APPSeCONNECT, an iPaaS Solution.

Issues and tasks for all these repositories are tracked here.

Process for contributing

You need a basic understanding of Git and GitHub.com.

Step 1: Skip this step for small changes. If you're interested in writing new content or in thoroughly revising existing content, open an issue describing what you want to do. The content inside the docs folder is organized into sections that are reflected in the Table of Contents (TOC). Define where the topic will be located in the TOC. Get feedback on your proposal.

-or-

You can also choose from existing issues for which community contributions are welcome. Projects for APPSeCONNECT Community contributors lists many of the work items that are available for commmunity contributors. Depending on your interests and level of commitment, you can choose from issues in the following categories:

• Maintenance. This category includes fairly simple contributions, such as fixing broken or incorrect links, adding missing code examples, or addressing limited content issues. In some cases, these issues may concern large numbers of files. In that case, you should let us know what you'd like to work on before you begin.

• Content updates. Given the enormity of the doc set, content easily becomes outdated and requires revision. In addition, for a variety of reason, some content has been duplicated or even triplicated. Updating content involves making sure that individual topics are current or revising content in a feature area to eliminate duplication and ensure that all unique content is preserved in the smaller documentation set.

• New content authoring. If you're interested in authoring your own topic, these issues list topics that we know we'd like to add to our doc set. Let us know before you begin working on a topic, though. If you're interested in writing a topic that isn't listed here, open an issue.

You can also look at our open issues list and volunteer to work on the ones you're interested in.

Step 2: Fork the /appseconnect/docs repo as needed and create a branch for your changes.

For small changes, you can use GitHub's web interface. Simply click the Edit the file in your fork of this project on the file you'd like to change. GitHub creates the new branch for you when you submit the changes.

Step 3: Make the changes on this new branch.

If it's a new topic, you can use this template file as your starting point. It contains the writing guidelines and also explains the metadata required for each article, such as author information.

Navigate to the folder that corresponds to the TOC location determined for your article in step 1. That folder contains the Markdown files for all articles in that section. If necessary, create a new folder to place the files for your content. The main article for that section is called index.md. For images and other static resources, create a subfolder called media inside the folder that contains your article, if it doesn't already exist. Inside the media folder, create a subfolder with the article name (except for the index file). Include larger samples in the samples folder under the root of the repo.

Be sure to follow the proper Markdown syntax. For more information, see the style guide.

Example structure

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
            portability_report.png

Step 4: Submit a Pull Request (PR) from your branch to appseconnect/docs/master.

Each PR should usually address one issue at a time. The PR can modify one or multiple files. If you're addressing multiple fixes on different files, separate PRs are preferred.

If your PR is addressing an existing issue, add the Fixes #Issue_Number keyword to the commit message or PR description. That way, the issue is automatically closed when the PR is merged. For more information, see Closing issues via commit messages.

The APPSeCONNECT team will review your PR and let you know if there are any other updates/changes necessary in order to approve it.

Step 5: Make any necessary updates to your branch as discussed with the team.

The maintainers will merge your PR into the master branch once feedback has been applied and your change is approved.

On a certain cadence, we push all commits from master branch into the live branch and then you'll be able to see your contribution live at https://docs.appseconnect.com/.

DOs and DON'Ts

The following list shows some guiding rules that you should keep in mind when you're contributing to the APPSeCONNECT documentation:

• DON'T surprise us with large pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time.
• DO read the style guide and voice and tone guidelines.
• DO use the template file as the starting point of your work.
• DO create a separate branch on your fork before working on the articles.
• DO follow the GitHub Flow workflow.
• DO blog and tweet (or whatever) about your contributions, frequently!

Note: you might notice that some of the topics are not currently following all the guidelines specified here and on the style guide as well. We're working towards achieving consistency throughout the site. Check the list of open issues we're currently tracking for that specific goal.