|
1 | | -Thanks for your interest in contributing! This document outlines how we expect contributions to happen. |
| 1 | +Thanks for your interest in contributing! We outline here how we expect contributions to happen. |
2 | 2 |
|
3 | 3 | WARNING: Note that contributions can only be made by individuals representing themselves, not by a company. |
4 | 4 |
|
| 5 | +## Overall contribution workflow |
| 6 | + |
5 | 7 | 1. Start by searching the [issue tracker](https://github.com/michelin/Continuous-Architecture-Toolkit/issues) to see if your contribution, be it a problem or a suggestion for an enhancement, was brought up before. |
6 | | -2. If nothing satisfying comes up, feel free to file a new issue. Provide as many details about your idea, problem, or suggestion as possible. |
7 | | -3. Once a conversation with one or more maintainers has taken place, it should become clear when it is appropriate to suggest a change via a pull request. |
8 | | -4. Fork the project repository and add materials on a topic of your choice. Then submit a pull request outlining your changes so maintainers can review what you've added and work with you to polish it. |
9 | | -5. Alternatively, propose edits to some assets directly in your browser. Select a file in the project repository by clicking on it. Locate and click the pencil icon at the top of every file in the repository. Make chages to the file in your browser, then submit that file for review. |
| 8 | +2. If nothing satisfying comes up, feel free to file a new issue. Provide as many details about your idea, problem, or suggestion as possible. Once a conversation with one or more maintainers has taken place, it should become clear when it is appropriate to suggest a change via a pull request. |
| 9 | +3. Create a branch with an explicit name and add materials on a topic of your choice. Then submit a pull request outlining your changes so maintainers can review what you've added and work with you to polish it. |
| 10 | + |
| 11 | +## Implement your fix or feature |
| 12 | + |
| 13 | +### Adding / Modifying Continuous Architecture framework content |
| 14 | + |
| 15 | +The [Continuous Architecture web site](https://continuous-architecture.org) is generated from the `landing/docs` folder where all pages are described using Asciidoc. Asciidoc is very similar to tradition markdown, here is a [reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) you can use. |
| 16 | + |
| 17 | +* `docs/case-studies`: contains one folder per case study we're publishing |
| 18 | +* `docs/framework`: describes the Continuous Architecture framework |
| 19 | +* `docs/glossary`: glossary pages of all the concepts we're using |
| 20 | +* `docs/manifest`: describes the Continuous Architecture Manifesto |
| 21 | +* `docs/practices`: one finds here all kits and practices we do use in Continuous Architecture. ADRs, team topologies, architecture runway ... |
| 22 | +* `docs/rituals`: all the different rituals and ceremonies we do recommend. Architecture peer review, Kata, team autonomy readiness ... |
| 23 | +* `docs/roles`: contains the roles we do promote like Product Architect, Fullstack Architect |
| 24 | +* `docs/start-your-journey`: describes the possible strategies to deploy Continuous Architecture within your organization |
| 25 | + |
| 26 | +Images are stored in subfolders of each of the above folders. You can reference them directly |
| 27 | + |
| 28 | +### Changing the look and feel |
| 29 | + |
| 30 | +Again in the `landing` folder, you'll find all ressources (html template pages, CSS styles) to modify the look and feel of the Continuous Architecture web site. |
| 31 | + |
| 32 | +* `_layouts`: contains all html templates in use |
| 33 | +* `_includes`: partial html templates embedded in layouts |
| 34 | +* `_sass`: contains syntactically awesome Stylesheets |
| 35 | +* `assets`: traditional web assets like css stylesheets, fonts, global images, javascript |
| 36 | +* `content/pages`: two mardown files (in YAML like syntax) that manage the content of the home and about us pages |
| 37 | + |
| 38 | +## Test and run locally |
| 39 | + |
| 40 | +You need to generate locally the Continuous Architecture web site to make sure your contribution is working and not generating regressions or side effects. |
| 41 | + |
| 42 | +### On Mac OS |
| 43 | + |
| 44 | +Before being able to generate locally the website, you need to install a couple of pre-requisites |
| 45 | + |
| 46 | +* RUBY |
| 47 | +* NodeJS & NPM: `brew install nvm` |
| 48 | +* Then you need to setup your shell. Here is an example for ZSH. `vi ~/.zshrc`: |
| 49 | + |
| 50 | +>export NVM_DIR="$HOME/.nvm" |
| 51 | + [ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh" # This loads nvm |
| 52 | + [ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" # This loads nvm bash_completion |
| 53 | + |
| 54 | +* Install the latest version of node: `nvm install --lts` |
| 55 | +* change the directory: `cd landing` |
| 56 | +* Install Postcss: `npm install postcss` |
| 57 | +* Install Yarn then add Tailwind (UI widget library we're using), `brew install yarn` then `yarn add tailwindcss@^1` |
| 58 | +* Install Gems needed by Jekyll with the following command `gem install bundler` then `bundle install`. It will read the Gemfile and load all needed dependencies. |
| 59 | + |
| 60 | +Finally, run the below command to |
| 61 | + |
| 62 | +* either build `JEKYLL_ENV=production jekyll build`. It will generate the files in the dist directory |
| 63 | +* or serve your website locally `JEKYLL_ENV=production jekyll serve`. It will allow you to view the generated website in your browser [127.0.0.1:4000](http://127.0.0.1:4000) |
| 64 | + |
| 65 | +## Create a Pull Request |
| 66 | + |
| 67 | +At this point, if your changes look good and tests are passing locally, you are ready to create a pull request. |
10 | 68 |
|
11 | | -== Getting Involved |
| 69 | +## Merging a PR and shipping the web site (maintainers only) |
12 | 70 |
|
13 | | -search our [issue tracker](https://github.com/michelin/Continuous-Architecture-Toolkit/issues) for issues with the "help wanted" label |
| 71 | +A PR can only be merged into master by a maintainer if tests are successful. Upon merge, our release GitHub Actions will take over to generate static html files then copy them to a Amazon S3 bucket. |
0 commit comments