|
1 | | -# Contributing to Ockam on GitHub |
| 1 | +Thank you for your interest in contributing to the Ockam open source projects. |
2 | 2 |
|
3 | | -We'd love for you to contribute to our source code and to make Ockam even better than it is today! Here are the guidelines we'd like you to follow: |
| 3 | +We have several documents on [Ockam.io](https://www.ockam.io/) that will help to guide you. |
4 | 4 |
|
5 | | -## Code of Conduct |
6 | | - |
7 | | -Help us keep Ockam open and inclusive. Please read and follow our [Code of Conduct][coc]. |
8 | | - |
9 | | -## Support |
10 | | - |
11 | | -Do not open issues for general support questions. We want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on dedicated support platforms, the best being the [Ockam Community Discussion][discuss]. |
12 | | - |
13 | | -As general hygiene, we will close all issues that are requests for general support and redirect people to the section you are reading right now. |
14 | | - |
15 | | -## Issues and Bugs |
16 | | - |
17 | | -If you find a bug in the source code, you can help us by submitting an issue to our [GitHub Repository][github]. Even better, you can submit a Pull Request with a fix. |
18 | | - |
19 | | -Before you submit your issue search the archive, maybe your question was already answered. |
20 | | - |
21 | | -If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues. |
22 | | - |
23 | | -In general, providing the following information will increase the chances of your issue being dealt with quickly: |
24 | | - |
25 | | -**Expected Behavior** - Is there documentation or an example that represents the discrepancy? |
26 | | - |
27 | | -**Actual Behavior** - Be sure to explain why this is a bug for you. |
28 | | - |
29 | | -**Steps to Reproduce the Problem** - Code snippets and screen shots are always helpful. |
30 | | - |
31 | | -**Environment** - What hardware, OS, and versions are you using? |
32 | | - |
33 | | -**Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might cause the problem (line of code or commit) |
34 | | - |
35 | | -Here is a great example of a well defined issue: [add link here when we have a good example] |
36 | | - |
37 | | -## Fix a doc |
38 | | - |
39 | | -If you have a suggestion for the documentation, you can open an issue and outline the problem or improvement you have - however, creating the doc fix yourself is much better! |
40 | | - |
41 | | -If you want to help improve the docs, it's a good idea to let others know what you're working on to minimize duplication of effort. Create a new issue (or comment on a related existing one) to let others know what you're working on. |
42 | | - |
43 | | -If you're making a small change (typo, phrasing) don't worry about filing an issue first. |
44 | | - |
45 | | -For large fixes, please build and test the documentation before submitting the PR to be sure you haven't accidentally introduced any layout or formatting issues on [Ockam.io/learn][learn]. You should also make sure that your commit message follows the *Commit Message Guidelines* below. |
46 | | - |
47 | | -## Build a Feature |
48 | | - |
49 | | -You can request a new feature by submitting an issue to our [GitHub Repository][github-issues]. |
50 | | - |
51 | | -If you would like to implement a new feature then consider what kind of change it is: |
52 | | - |
53 | | -* **Major Changes** that you wish to contribute to the project should be discussed first in an [GitHub issue][github-issues] that clearly outlines the changes and benefits of the feature. Be sure to read our *Issue Submission Guidelines* above. |
54 | | - |
55 | | -* **Small Changes** can directly be crafted and submitted to the [GitHub Repository][github] as a Pull Request. |
56 | | - |
57 | | -Be sure to follow Ockam's language specific format. |
58 | | - |
59 | | -## Commit Messages |
60 | | - |
61 | | -Each commit message consists of a header, a body, and a footer. |
62 | | - |
63 | | -The header includes a type, a scope and a subject: |
64 | | - |
65 | | -``` |
66 | | -<type>(<scope>): <subject> |
67 | | -<BLANK LINE> |
68 | | -<body> |
69 | | -<BLANK LINE> |
70 | | -<footer> |
71 | | -``` |
72 | | - |
73 | | -`<subject>` is _required_, must not be longer that 100 characters |
74 | | - |
75 | | -`<type>` is _required_, must be in lower case, and have one of the below values. |
76 | | - |
77 | | - * `build:` changes that affect our build system or external dependencies |
78 | | - * `chore:` some minor change that doesn't fall in any of the other types |
79 | | - * `ci:` changes to our continuous integration configuration files |
80 | | - * `docs:` a documentation only change |
81 | | - * `feat:` a new feature |
82 | | - * `content:` updates or additions to Ockam.io/learn |
83 | | - |
84 | | -`<scope>` is optional, when used it must be in lower case and have one of the below values: 'c', 'elixir', 'go', 'javascript', 'rust', 'swift'. |
85 | | - |
86 | | -`<subject>` is _required_, must be lower case and not end in period. Also be sure to describe your changes in the imperative-mood. |
87 | | - |
88 | | -`<body>` is optional, must be max 100 chars wide, must have a blank line before it. Be sure to describe your changes in the imperative-mood. |
89 | | - |
90 | | -`<footer>` is optional, must not be longer that 100 characters. |
91 | | - |
92 | | -**Ockam requires that all commits are signed by your PGP key.** |
93 | | - |
94 | | -If signing git commits is new to you, we recommend that you use Krypton. |
95 | | -Instructions for signing git commits with Krypton can be found [here][sign] |
96 | | - |
97 | | -## Pull Requests |
98 | | - |
99 | | -Before you submit your pull request consider the following guidelines: |
100 | | - |
101 | | -* Search [GitHub][github-pulls] for an open or closed Pull Request that relates to your submission. You don't want to duplicate effort. |
102 | | -* Fork the repository and make your changes in a new git branch using the branch naming convention `username/feature`. |
103 | | -* This is the fun part! Build your feature. |
104 | | -* If the changes affect public APIs, change or add relevant documentation. |
105 | | -* If you have formatting errors your PR will be rejected by our build tools. |
106 | | -* Ockam requires that all commits are signed by your PGP key. If signing git commits is new to you, we recommend that you use Krypton. Instructions for signing git commits with Krypton can be found [here][sign]. |
107 | | -* Commit your changes using a descriptive commit message that follows our commit message conventions. |
108 | | -* Be sure to squash your commits in your feature branch. |
109 | | -* Push your local feature branch to GitHub |
110 | | -* In GitHub, send a pull request to `ockam:develop`. |
111 | | -* The Ockam Contributor License Agreement tool will check to see if you've signed our CLA. If you have not yet done so, the PR will be blocked. The fix is easy. Simply fork our [contributors repository](https://github.com/ockam-network/contributors/), append your information to the [CONTRIBUTORS.csv](https://github.com/ockam-network/contributors/blob/main/CONTRIBUTORS.csv), and create a new PR. Be sure to read the CLA during the process. |
112 | | -* Look at the 'Checks' user experience on github.com. We trigger a process to check that your code follows the guidelines set out in this contributor guide. |
113 | | -* If you find that our CI has failed, look into the logs on Azure Pipelines to find out if your changes caused test failures, the commit message was malformed, etc. If you find that the tests failed or times out for unrelated reasons, you should reach out to an Ockam team member in the [Ockam Community][discuss] so that the build can be restarted. |
114 | | -* If we suggest changes, then: |
115 | | - |
116 | | - ** Make the required updates. |
117 | | - ** Re-run the Ockam test suite to ensure tests are still passing. |
118 | | - ** Commit your changes to your feature branch (e.g. `username/feature`). |
119 | | - ** Squash your commit history and rebase your feature branch to the current version of `ockam:develop`. |
120 | | - ** Push the changes to your feature branch. This will update your Pull Request. |
121 | | - |
122 | | -That's it! Thank you for your contribution! |
123 | | - |
124 | | - |
125 | | -## Contributor License Agreement (CLA) |
126 | | - |
127 | | -When you submit a Pull Request, a bot will ask you to sign our CLA if you haven't done so before. This is necessary for documentation changes, too. Be sure to read the CLA! |
128 | | - |
129 | | - It's a quick process, we promise! |
130 | | - |
131 | | - [You can find Ockam's CLA here.][cla] |
132 | | - |
133 | | -* If you work for a Corporation and your commits are part of a corporate backed project, please [reach out to the Ockam Team via email][corporate-cla] so we can send your legal department our corporate CLA via Docusign. |
134 | | - |
135 | | -## References |
136 | | -Thank you to the AngularJS community, this contributor guide was inspired by your format and content. |
137 | | - |
138 | | -[coc]: https://www.ockam.io/learn/how-to-guides/high-performance-team/conduct |
139 | | -[learn]: https://ockam.io/learn |
140 | | -[corporate-cla]: mailto:[email protected] |
141 | | -[cla]: https://www.ockam.io/learn/how-to-guides/contributing/cla/ |
142 | | -[github-issues]: https://github.com/ockam-network/ockam/issues |
143 | | -[github-new-issue]: https://github.com/ockam-network/ockam/issues/new |
144 | | -[github-pulls]: https://github.com/ockam-network/ockam/pulls |
145 | | -[github]: https://github.com/ockam-network |
146 | | -[sign]:https://krypt.co/docs/start/code-signing.html |
147 | | -[discuss]: https://github.com/ockam-network/ockam/discussions |
| 5 | +You can find Ockam's library of contributing guides here: |
| 6 | +[https://www.ockam.io/learn/how-to-guides/contributing/CONTRIBUTING](https://www.ockam.io/learn/how-to-guides/contributing/CONTRIBUTING) |
0 commit comments